{{- .Title -}}
+{{ .Description | markdownify }}
+diff --git a/assets/scss/_sidebar-toc.scss b/assets/scss/_sidebar-toc.scss index 96e7abbb16..a752729f48 100644 --- a/assets/scss/_sidebar-toc.scss +++ b/assets/scss/_sidebar-toc.scss @@ -1,7 +1,7 @@ // // Right side toc // -.td-toc { +.td-sidebar-toc { border-left: 1px solid $border-color; @supports (position: sticky) { @@ -16,6 +16,17 @@ padding-bottom: 1.5rem; vertical-align: top; +} + +.td-page-meta { + a { + display: block; + font-weight: $font-weight-medium; + } +} + +.td-toc { + a { display: block; font-weight: $font-weight-light; @@ -31,12 +42,6 @@ margin-left: 0.5rem; } - .td-page-meta { - a { - font-weight: $font-weight-medium; - } - } - #TableOfContents { // Hugo's ToC is a mouthful, this can be used to style the top level h2 entries. > ul > li > ul > li > a {} diff --git a/assets/scss/_taxonomy.scss b/assets/scss/_taxonomy.scss new file mode 100644 index 0000000000..538014057f --- /dev/null +++ b/assets/scss/_taxonomy.scss @@ -0,0 +1,332 @@ +// Taxonomies - e.g. Tags, Categories, ... + +.taxonomy-terms-article { + width: 100%; + clear: both; + font-size: 0.8rem; + + .taxonomy-title { + display: inline; + font-size: 1.25em; + height: 1em; + line-height: 1em; + margin-right: 0.5em; + padding: 0; + } +} + +.taxonomy-terms-cloud { + width: 100%; + clear: both; + font-size: 0.8rem; + + .taxonomy-title { + display: inline-block; + width: 100%; + font-size: 1rem; + font-weight: 700; + color: $primary; + border-bottom: 1px $primary solid; + margin-bottom: 1em; + padding-bottom: 0.375rem; + margin-top: 1em; + } +} + +.taxonomy-terms-page { + max-width: 800px; + margin: auto; + + h1 { + margin-bottom: 1em; + } + + .taxonomy-terms-cloud { + font-size: 1em; + + li { + display: block; + } + } + + .taxo-text-tags { + + li + li::before { + content: none; + } + } + + .taxo-fruits { + + .taxonomy-count, + .taxonomy-label { + display: inherit; + font-size: 1rem; + margin: 0; + padding: 0; + padding-right: 0.5em; + } + + .taxonomy-count::before { + content: "("; + } + .taxonomy-count::after { + content: ")"; + } + } +} + +.taxonomy-terms { + list-style: none; + margin: 0; + overflow: hidden; + padding: 0; + display: inline; + + li { + // https://stackoverflow.com/questions/3247358/how-do-i-wrap-text-with-no-whitespace-inside-a-td + display: inline; + overflow-wrap: break-word; + word-wrap: break-word; + -ms-word-break: break-all; + word-break: break-all; + word-break: break-word; + -ms-hyphens: auto; + -moz-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; + } +} + +.taxonomy-count { + font-size: 0.8em; + line-height: 1.25em; + display: inline-block; + padding-left: 0.6em; + padding-right: 0.6em; + margin-left: 0.6em; + text-align: center; + border-radius: 1em; + background-color: $white; +} + +.taxonomy-term { + background: $gray-200; + border-width: 0; + border-radius: 0 3px 3px 0; + color: $gray-600; + display: inline-block; + font-size: 1em; + line-height: 1.5em; + min-height: 1.5em; + max-width: 100%; + padding: 0 0.5em 0 1em; + position: relative; + margin: 0 0.5em 0.2em 0; + text-decoration: none; + -webkit-transition: color 0.2s; + -webkit-clip-path: polygon(100% 0,100% 100%,0.8em 100%,0 50%,0.8em 0); + clip-path: polygon(100% 0,100% 100%,0.8em 100%,0 50%,0.8em 0); + + &:hover { + background-color: $primary; + color: $white; + + .taxonomy-count{ + color: $dark!important; + } + } + + &:hover::before { + background: $primary; + } +} + +// Example for simple tags layout +.taxo-text-tags { + + .taxonomy-term { + background: none; + border-width: 0; + border-radius: 0; + color: $gray-600; + font-size: 1em; + line-height: 1.5em; + min-height: 1.5em; + max-width: 100%; + padding: 0; + position: relative; + margin: 0; + text-decoration: none; + -webkit-clip-path: none; + clip-path: none; + + &:hover { + background: none; + color: $link-color; + + .taxonomy-count{ + color: $dark!important; + } + } + + &:hover::before { + background: none; + } + } + + li + li::before { + content: "|"; + color: $gray-600; + margin-right: 0.2em; + } + + .taxonomy-count { + font-size: 1em; + line-height: 1.25em; + display: inline-block; + padding: 0; + margin: 0; + text-align: center; + border-radius: 0; + background: none; + vertical-align: super; + font-size: 0.75em; + } + + .taxonomy-term:hover .taxonomy-count { + color: $link-color !important; + } +} + +// Example for icon tags +.taxo-fruits { + + .taxonomy-term[data-taxonomy-term]::before { + font-style: normal; + font-variant: normal; + text-rendering: auto; + -webkit-font-smoothing: antialiased; + font-family: "Font Awesome 5 Free"; + // font-weight: 900; + padding-right: 0.5em; + font-size: 2em; + min-width: 1.5em; + display: inline-block; + } + + .taxonomy-term[data-taxonomy-term="apple"]::before { + content: "\f5d1"; + color: red; + } + + .taxonomy-term[data-taxonomy-term="carrot"]::before { + content: "\f787"; + color: orange; + } + + .taxonomy-term[data-taxonomy-term="lemon"]::before { + content: "\f094"; + color: limegreen; + } + + .taxonomy-term[data-taxonomy-term="pepper"]::before { + content: "\f816"; + color: darkred; + } + + .taxonomy-term { + background: none; + border-width: 0; + border-radius: 0; + color: $gray-600; + font-size: 1em; + line-height: 2.5em; + max-width: 100%; + padding: 0; + position: relative; + margin: 0; + text-decoration: none; + -webkit-clip-path: none; + clip-path: none; + + &:hover { + background: none; + color: $link-color; + + .taxonomy-count{ + color: $dark!important; + } + } + + &:hover::before { + background: none; + text-shadow: 0 0 3px $gray-900; + } + } + + .taxonomy-count, + .taxonomy-label { + display: none; + } + + &.taxonomy-terms-article { + margin-bottom: 1rem; + + .taxonomy-title { + display: none; + } + } +} + +.taxonomy-taxonomy-page { + max-width: 800px; + margin: auto; + + h1 { + margin-bottom: 1em; + } +} + +.article-meta { + margin-bottom: 1.5rem; +} + +.article-teaser.article-type-docs h3 a:before { + display: inline-block; + font-style: normal; + font-variant: normal; + text-rendering: auto; + -webkit-font-smoothing: antialiased; + font-family: "Font Awesome 5 Free"; + content: "\f02d"; + padding-right: 0.5em; +} + +.article-teaser.article-type-blog h3 a:before { + display: inline-block; + font-style: normal; + font-variant: normal; + text-rendering: auto; + -webkit-font-smoothing: antialiased; + font-family: "Font Awesome 5 Free"; + content: "\f781"; + padding-right: 0.5em; +} + +.all-taxonomy-terms { + font-weight: 500; + line-height: 1.2; + font-size: 1.5rem; + + &:before { + display: inline-block; + font-style: normal; + font-variant: normal; + text-rendering: auto; + -webkit-font-smoothing: antialiased; + font-family: "Font Awesome 5 Free"; + content: "\f122"; + padding-right: 0.5em; + } +} \ No newline at end of file diff --git a/assets/scss/main.scss b/assets/scss/main.scss index 1992c27038..cca86aabd2 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -26,6 +26,7 @@ @import "blocks/blocks"; @import "section-index"; @import "pageinfo"; +@import "taxonomy"; @if $td-enable-google-fonts { @import url($web-font-path); diff --git a/i18n/de.toml b/i18n/de.toml index cec9c52ad4..9feabce51a 100644 --- a/i18n/de.toml +++ b/i18n/de.toml @@ -18,6 +18,10 @@ other = "Diese Seite durchsuchen…" [ui_in] other = "in" +# Used in sentences such as "All Tags" +[ui_all] +other = "alle" + # Footer text [footer_all_rights_reserved] other = "Alle Rechte vorbehalten" diff --git a/i18n/en.toml b/i18n/en.toml index 857a2ad70c..6f1360b365 100644 --- a/i18n/en.toml +++ b/i18n/en.toml @@ -18,6 +18,10 @@ other = "Search this site…" [ui_in] other = "in" +# Used in sentences such as "All Tags" +[ui_all] +other = "all" + # Footer text [footer_all_rights_reserved] other = "All Rights Reserved" diff --git a/layouts/_default/content.html b/layouts/_default/content.html index f6f47475ad..3453011292 100644 --- a/layouts/_default/content.html +++ b/layouts/_default/content.html @@ -1,9 +1,21 @@
{{ .Description | markdownify }}
+{{ .Date.Format ($.Param "time_format_blog") }} {{ T "ui_in"}} {{ .CurrentSection.LinkTitle }}
+{{ .Plain | safeHTML | truncate 250 }}
diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html index 5df82a7e4c..20af4e6526 100644 --- a/layouts/docs/baseof.html +++ b/layouts/docs/baseof.html @@ -10,12 +10,14 @@+ git clone --recurse-submodules --depth 1 https://github.com/my/example.git ++ +You can now edit your local versions of the site's source files. To preview your site, go to your site root directory and run `hugo server` ([see the known issues on MacOS](#known-issues)). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use `git push`. + +#### Using the command line + +To copy the example site: + +1. Make a local working copy of the example site directly using `git clone`: + + git clone https://github.com/google/docsy-example.git + +1. Switch to the root of the cloned project, for example: + + cd docsy-example + +1. Get local copies of the project submodules so you can build and run your site locally: + + git submodule update --init --recursive + +1. Build your site: + + hugo server + +1. Preview your site in your browser at: http://localhost:1313/. You can use `Ctrl + c` to stop the Hugo server whenever you like. + [See the known issues on MacOS](#known-issues). + +1. Now that you have a site running, you can push it to a new repository: + + 1. [Create a new repository in GitHub](https://help.github.com/en/articles/create-a-repo) + for your site with your chosen repo name. For clarity you may also want to rename the root + directory (`docsy-example`) of your working copy to match, though everything will still + work even if you don't. + + 1. Configure + [`origin`](https://help.github.com/en/articles/configuring-a-remote-for-a-fork) + in your project. From your site's root directory, set the URL for `origin` to your new + repo (otherwise you'll be trying to push changes to `google/docsy` rather than to your repo): + + git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git + + + 1. Verify that your remote is configured correctly by running: + + git remote -v + + + 1. Push your Docsy site to your repository: + + git push -u origin master + +### Option 2: Use the Docsy theme in your own site + +Specify the [Docsy theme](https://github.com/google/docsy) like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you'll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project's `themes` subdirectory. + +Whichever approach you use, for simplicity we recommend copying and editing our [example site configuration](#basic-site-configuration) for your project, or you may get Hugo errors for missing parameters and values when you try to build your site. + +#### Using the Docsy theme as a submodule + +Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project +always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in +your repo that may result in merge conflicts when you try to update it. This is the approach used by our +[example project](https://github.com/google/docsy-example). + + +To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project's root directory. + +```shell +hugo new site myproject +cd myproject +git init +git submodule add https://github.com/google/docsy.git themes/docsy +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +To add the Docsy theme to an existing site, run the following commands from your project's root directory: + +``` +git submodule add https://github.com/google/docsy.git themes/docsy +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +#### Cloning the Docsy theme to your project's `themes` subdirectory + +If you don't want to use a submodules (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project. + + + + +To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory: + +``` +cd themes +git clone https://github.com/google/docsy +``` + +If you want to build and/or serve your site [locally](/docs/deployment/#serving-your-site-locally), you also need to get local copies of the theme’s own submodules: + +``` +git submodule update --init --recursive +``` + +For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site. + +#### Preview your site + +To build and preview your site locally: + +``` +cd myproject +hugo server +``` + +By default, your site will be available at http://localhost:1313/. [See the known issues on MacOS](#known-issues). + +## Basic site configuration + +Site-wide configuration details and parameters are defined in your project's `config.toml` file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`config.toml` in the example project](https://github.com/google/docsy-example/blob/master/config.toml) for how to add this information. **We recommend copying this `config.toml` and editing it even if you're just using the theme and not copying the entire Docsy example site**. + +The Docsy example site comes with some defaults you may want to remove or customize straight away: + +### Internationalization + +The Docsy example site supports content in English and Norwegian. You can find out more about how Docsy supports multi-language content in [Multi-language support](/docs/language/). + +If you don't intend to translate your site to Norwegian, you can remove the language switcher by removing the following lines from `config.toml`: + +``` +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +``` + +To remove the translated source files, delete the `docsy-example/content/no` directory. + +### Search + +By default, the Docsy example site uses its own [Google Custom Search Engine](https://cse.google.com/cse/all). To disable this site search, delete or comment out the following lines: + +``` +# Google Custom Search Engine ID. Remove or comment out to disable search. +gcs_engine_id = "011737558837375720776:fsdu1nryfng" +``` + +To use your own Custom Search Engine, replace the value in the `gcs_engine_id` with the ID of your own search engine. Or [choose another search option](/docs/adding-content/navigation/#site-search-options). + +## Known issues + +### MacOS + +#### Errors: `too many open files` or `fatal error: pipe failed` + +By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you're simultaneously running multiple applications, +you might receive one of the following errors when you run [`hugo server`](https://gohugo.io/commands/hugo_server/) to preview your site locally: + +* POSTCSS v7 and earlier: + + ``` + ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files + ``` +* POSTCSS v8 and later: + + ``` + fatal error: pipe failed + ``` + +##### Workaround + +To temporarily allow more open files: + +1. View your current settings by running: + + ``` + sudo launchctl limit maxfiles + ``` + +2. Increase the limit to `65535` files by running the following commands. If your site has fewer files, you can set choose to set lower soft (`65535`) and + hard (`200000`) limits. + + ```shell + sudo launchctl limit maxfiles 65535 200000 + ulimit -n 65535 + sudo sysctl -w kern.maxfiles=200000 + sudo sysctl -w kern.maxfilesperproc=65535 + ``` + +Note that you might need to set these limits for each new shell. +[Learn more about these limits and how to make them permanent](https://www.google.com/search?q=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com&oq=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com). + +## What's next? + +* [Add content and customize your site](/docs/adding-content/) +* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/). +* [Publish your site](/docs/deployment/). + diff --git a/userguide/content/en/docs/dev-test-content/Getting started/Getting started copy/quickstart-docker.md b/userguide/content/en/docs/dev-test-content/Getting started/Getting started copy/quickstart-docker.md new file mode 100755 index 0000000000..6ae3255179 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Getting started/Getting started copy/quickstart-docker.md @@ -0,0 +1,81 @@ + +--- +title: "Docker Quickstart" +linkTitle: "Docker Quickstart" +weight: 3 +date: 2018-07-30 +description: > + This page helps you to setup and run a local Docsy site with Docker in 5 minutes. +--- + +## Install the prerequisites + +1. On Mac and Windows, download and install [Docker + Desktop](ihttps://www.docker.com/get-started). On Linux, install [Docker + engine](https://docs.docker.com/engine/install/#server) and [Docker + compose](https://docs.docker.com/compose/install/). + + The installation may require you to reboot your computer for the changes to + take effect. + +1. [Install git](https://github.com/git-guides/install-git). + +## Create your repository from the docsy-example template + +The docsy-example repository provides a basic site structure that you can use +as starting point to create your own documentation. + +1. Use the [docsy-example template](https://github.com/google/docsy-example) + to [create your own repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). + +1. Download the code to your local machine by [cloning your newly created + repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository). + +1. Change your working directory to the newly created folder: + + ```bash + cd docsy-example + ``` + +## Build and run the container + +The docsy-example repository includes a +[Dockerfile](https://docs.docker.com/engine/reference/builder/) that you can +use to run your site. + +1. Build the docker image: + + ```bash + docker-compose build + ``` + +1. Run the built image: + + ```bash + docker-compose up + ``` + +1. Open the address `http://localhost:1313` in your web browser to load the + docsy-example homepage. You can now make changes to the source files, those + changes will be live-reloaded in your browser. + +## Cleanup + +To cleanup your system and delete the container image follow the next steps. + +1. Stop Docker Compose with **Ctrl + C**. + +1. Remove the produced images + + ```bash + docker-compose rm + ``` + +## What's next? + +* Learn about [basic setup and configurations for Docsy](/docs/getting-started/). +* [Add content and customize your site](/docs/adding-content/) +* [Publish your site](/docs/deployment/). + + + diff --git a/userguide/content/en/docs/dev-test-content/Getting started/_index.md b/userguide/content/en/docs/dev-test-content/Getting started/_index.md new file mode 100755 index 0000000000..5aeb8cc684 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Getting started/_index.md @@ -0,0 +1,317 @@ + +--- +title: "Getting Started" +linkTitle: "Getting Started" +weight: 2 +date: 2018-07-30 +icon: fas fa-exclamation +description: > + This page tells you how to get started with the Docsy theme, including installation and basic configuration. +--- + + +## Prerequisites and installation + +### Use our Docker image + +We provide a Docker image that you can use to run and test your Docsy site +locally, without having to install all Docsy's dependencies. + +You can see how to get started with this approach by following our [Docker +Quickstart tutorial](quickstart-docker). If you don't want to use Docker, +follow the instructions below to install Hugo and PostCSS. + +### Install Hugo + +You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.75.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. + +For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/). + +#### Linux + +Be careful using `sudo apt-get install hugo`, as it [doesn't get you the `extended` version for all Debian/Ubuntu versions](https://gohugo.io/getting-started/installing/#debian-and-ubuntu), and may not be up-to-date with the most recent Hugo version. + +If you've already installed Hugo, check your version: + +``` +hugo version +``` +If the result is `v0.75` or earlier, or if you don't see `Extended`, you'll need to install the latest version. You can see a complete list of Linux installation options in [Install Hugo](https://gohugo.io/getting-started/installing/#linux). The following shows you how to install Hugo from the release page: + +1. Go to the [Hugo releases](https://github.com/gohugoio/hugo/releases) page. +2. In the most recent release, scroll down until you find a list of + **Extended** versions. +3. Download the latest extended version (`hugo_extended_0.5X_Linux-64bit.tar.gz`). +4. Create a new directory: + + mkdir hugo + +5. Extract the files you downloaded to `hugo`. + +6. Switch to your new directory: + + cd hugo + +7. Install Hugo: + + sudo install hugo /usr/bin + +#### macOS + +Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos). + +#### As an `npm` module + +You can install Hugo as an `npm` module using [`hugo-bin`](https://www.npmjs.com/package/hugo-bin). This adds `hugo-bin` to your `node_modules` folder and adds the dependency to your `package.json` file. To install the extended version of Hugo: + +``` +npm install hugo-extended --save-dev +``` + +See the [`hugo-bin` documentation](https://www.npmjs.com/package/hugo-bin) for usage details. + +### Install PostCSS + +To build or update your site's CSS resources, you also need [`PostCSS`](https://postcss.org/) to create the final assets. If you need to install it, you must have a recent version of [NodeJS](https://nodejs.org/en/) installed on your machine so you can use `npm`, the Node package manager. By default `npm` installs tools under the directory where you run [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install#description): + +``` +sudo npm install -D autoprefixer +sudo npm install -D postcss-cli +``` + +Starting in [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md), you must also separately install `postcss`: + +``` +sudo npm install -D postcss +``` + +Note that versions of `PostCSS` later than 5.0.1 will not load `autoprefixer` if installed [globally](https://flaviocopes.com/npm-packages-local-global/), you must use a local install. + +## Using the theme + +To use the Docsy Hugo theme, you have a couple of options: + +* **Copy and edit the source for the [Docsy example site](https://github.com/google/docsy-example).** This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site uses Docsy as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so it's easy to [keep up to date](/docs/updating/). +* **Build your own site using the Docsy theme.** Specify the [Docsy theme](https://github.com/google/docsy) like any other [Hugo theme](https://gohugo.io/themes/) when creating or updating your site. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. + +### Option 1: Copy the Docsy example site + +The [Example Site](https://example.docsy.dev) gives you a good starting point for building your docs site and is +pre-configured to use the Docsy theme as a Git submodule. You can copy the Example Site either by: + +* [Using the GitHub UI](#using-the-github-ui) +* [Using the command line](#using-the-command-line) + +#### Using the GitHub UI + +This is the simplest approach, as the Docsy example site repo is a [template repository](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/). To create your own copy of the Docsy example site repo: + +1. Go to the [repo page](https://github.com/google/docsy-example) and click **Use this template**. + +1. Type your chosen name for your new repository in the **Repository name** field. You can also add an optional **Description**. + +1. Click **Create repository from template** to create your new repository. Congratulations, you now have a Docsy site repo! + +1. To test your copied site locally with Hugo, or make local edits, you'll also need to make a local copy of your new repository. To do this, use `git clone`, replacing `https://github.com/my/example.git` with your repo's web URL (don't forget to use `--recurse-submodules` or you won't pull down some of the code you need to generate a working site): + +
+ git clone --recurse-submodules --depth 1 https://github.com/my/example.git ++ +You can now edit your local versions of the site's source files. To preview your site, go to your site root directory and run `hugo server` ([see the known issues on MacOS](#known-issues)). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use `git push`. + +#### Using the command line + +To copy the example site: + +1. Make a local working copy of the example site directly using `git clone`: + + git clone https://github.com/google/docsy-example.git + +1. Switch to the root of the cloned project, for example: + + cd docsy-example + +1. Get local copies of the project submodules so you can build and run your site locally: + + git submodule update --init --recursive + +1. Build your site: + + hugo server + +1. Preview your site in your browser at: http://localhost:1313/. You can use `Ctrl + c` to stop the Hugo server whenever you like. + [See the known issues on MacOS](#known-issues). + +1. Now that you have a site running, you can push it to a new repository: + + 1. [Create a new repository in GitHub](https://help.github.com/en/articles/create-a-repo) + for your site with your chosen repo name. For clarity you may also want to rename the root + directory (`docsy-example`) of your working copy to match, though everything will still + work even if you don't. + + 1. Configure + [`origin`](https://help.github.com/en/articles/configuring-a-remote-for-a-fork) + in your project. From your site's root directory, set the URL for `origin` to your new + repo (otherwise you'll be trying to push changes to `google/docsy` rather than to your repo): + + git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git + + + 1. Verify that your remote is configured correctly by running: + + git remote -v + + + 1. Push your Docsy site to your repository: + + git push -u origin master + +### Option 2: Use the Docsy theme in your own site + +Specify the [Docsy theme](https://github.com/google/docsy) like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you'll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project's `themes` subdirectory. + +Whichever approach you use, for simplicity we recommend copying and editing our [example site configuration](#basic-site-configuration) for your project, or you may get Hugo errors for missing parameters and values when you try to build your site. + +#### Using the Docsy theme as a submodule + +Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project +always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in +your repo that may result in merge conflicts when you try to update it. This is the approach used by our +[example project](https://github.com/google/docsy-example). + + +To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project's root directory. + +```shell +hugo new site myproject +cd myproject +git init +git submodule add https://github.com/google/docsy.git themes/docsy +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +To add the Docsy theme to an existing site, run the following commands from your project's root directory: + +``` +git submodule add https://github.com/google/docsy.git themes/docsy +echo 'theme = "docsy"' >> config.toml +git submodule update --init --recursive +``` + +#### Cloning the Docsy theme to your project's `themes` subdirectory + +If you don't want to use a submodules (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project. + + + + +To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory: + +``` +cd themes +git clone https://github.com/google/docsy +``` + +If you want to build and/or serve your site [locally](/docs/deployment/#serving-your-site-locally), you also need to get local copies of the theme’s own submodules: + +``` +git submodule update --init --recursive +``` + +For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site. + +#### Preview your site + +To build and preview your site locally: + +``` +cd myproject +hugo server +``` + +By default, your site will be available at http://localhost:1313/. [See the known issues on MacOS](#known-issues). + +## Basic site configuration + +Site-wide configuration details and parameters are defined in your project's `config.toml` file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`config.toml` in the example project](https://github.com/google/docsy-example/blob/master/config.toml) for how to add this information. **We recommend copying this `config.toml` and editing it even if you're just using the theme and not copying the entire Docsy example site**. + +The Docsy example site comes with some defaults you may want to remove or customize straight away: + +### Internationalization + +The Docsy example site supports content in English and Norwegian. You can find out more about how Docsy supports multi-language content in [Multi-language support](/docs/language/). + +If you don't intend to translate your site to Norwegian, you can remove the language switcher by removing the following lines from `config.toml`: + +``` +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +``` + +To remove the translated source files, delete the `docsy-example/content/no` directory. + +### Search + +By default, the Docsy example site uses its own [Google Custom Search Engine](https://cse.google.com/cse/all). To disable this site search, delete or comment out the following lines: + +``` +# Google Custom Search Engine ID. Remove or comment out to disable search. +gcs_engine_id = "011737558837375720776:fsdu1nryfng" +``` + +To use your own Custom Search Engine, replace the value in the `gcs_engine_id` with the ID of your own search engine. Or [choose another search option](/docs/adding-content/navigation/#site-search-options). + +## Known issues + +### MacOS + +#### Errors: `too many open files` or `fatal error: pipe failed` + +By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you're simultaneously running multiple applications, +you might receive one of the following errors when you run [`hugo server`](https://gohugo.io/commands/hugo_server/) to preview your site locally: + +* POSTCSS v7 and earlier: + + ``` + ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files + ``` +* POSTCSS v8 and later: + + ``` + fatal error: pipe failed + ``` + +##### Workaround + +To temporarily allow more open files: + +1. View your current settings by running: + + ``` + sudo launchctl limit maxfiles + ``` + +2. Increase the limit to `65535` files by running the following commands. If your site has fewer files, you can set choose to set lower soft (`65535`) and + hard (`200000`) limits. + + ```shell + sudo launchctl limit maxfiles 65535 200000 + ulimit -n 65535 + sudo sysctl -w kern.maxfiles=200000 + sudo sysctl -w kern.maxfilesperproc=65535 + ``` + +Note that you might need to set these limits for each new shell. +[Learn more about these limits and how to make them permanent](https://www.google.com/search?q=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com&oq=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com). + +## What's next? + +* [Add content and customize your site](/docs/adding-content/) +* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/). +* [Publish your site](/docs/deployment/). + diff --git a/userguide/content/en/docs/dev-test-content/Getting started/quickstart-docker.md b/userguide/content/en/docs/dev-test-content/Getting started/quickstart-docker.md new file mode 100755 index 0000000000..6ae3255179 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Getting started/quickstart-docker.md @@ -0,0 +1,81 @@ + +--- +title: "Docker Quickstart" +linkTitle: "Docker Quickstart" +weight: 3 +date: 2018-07-30 +description: > + This page helps you to setup and run a local Docsy site with Docker in 5 minutes. +--- + +## Install the prerequisites + +1. On Mac and Windows, download and install [Docker + Desktop](ihttps://www.docker.com/get-started). On Linux, install [Docker + engine](https://docs.docker.com/engine/install/#server) and [Docker + compose](https://docs.docker.com/compose/install/). + + The installation may require you to reboot your computer for the changes to + take effect. + +1. [Install git](https://github.com/git-guides/install-git). + +## Create your repository from the docsy-example template + +The docsy-example repository provides a basic site structure that you can use +as starting point to create your own documentation. + +1. Use the [docsy-example template](https://github.com/google/docsy-example) + to [create your own repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). + +1. Download the code to your local machine by [cloning your newly created + repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository). + +1. Change your working directory to the newly created folder: + + ```bash + cd docsy-example + ``` + +## Build and run the container + +The docsy-example repository includes a +[Dockerfile](https://docs.docker.com/engine/reference/builder/) that you can +use to run your site. + +1. Build the docker image: + + ```bash + docker-compose build + ``` + +1. Run the built image: + + ```bash + docker-compose up + ``` + +1. Open the address `http://localhost:1313` in your web browser to load the + docsy-example homepage. You can now make changes to the source files, those + changes will be live-reloaded in your browser. + +## Cleanup + +To cleanup your system and delete the container image follow the next steps. + +1. Stop Docker Compose with **Ctrl + C**. + +1. Remove the produced images + + ```bash + docker-compose rm + ``` + +## What's next? + +* Learn about [basic setup and configurations for Docsy](/docs/getting-started/). +* [Add content and customize your site](/docs/adding-content/) +* [Publish your site](/docs/deployment/). + + + diff --git a/userguide/content/en/docs/dev-test-content/Language/Language copy/Language/_index.md b/userguide/content/en/docs/dev-test-content/Language/Language copy/Language/_index.md new file mode 100644 index 0000000000..6c522471af --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Language/Language copy/Language/_index.md @@ -0,0 +1,60 @@ +--- +title: "Multi-language Support" +linkTitle: "Multi-language Support" +weight: 7 +description: > + Support multiple languages in your site. +--- + +If you'd like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions. + +## Content and configuration + +To add content in multiple languages, you first need to define the available languages in a `languages` section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English: + +```toml +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +... +[languages] +[languages.en] +title = "Docsy" +description = "Docsy does docs" +languageName ="English" +# Weight used for sorting. +weight = 1 +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" +``` + +Any setting not defined in a `[languages]` block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be `content/en` unless the user selects the Norwegian language option. + +Once you've updated your site config, you create a content root directory for each language version in your source repo, such as `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information. + +{{% alert title="Tip" %}} +If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language. +{{% /alert %}} + +For adding multiple language versions of other site elements such as button text, see the [internationalization bundles](#internationalization-bundles) section below. + +## Selecting a language + +If you configure more than one language in `config.toml`, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language. + +## Internationalization bundles + +All UI strings (text for buttons etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. + +If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of `en.toml` called `jp.toml`), we recommend you do this **in the theme** rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project's `/i18n` folder. + +{{% alert title="Hugo Tip" %}} +Run `hugo server --i18n-warnings` when doing translation work, as it will give you warnings on what strings are missing. +{{% /alert %}} + + diff --git a/userguide/content/en/docs/dev-test-content/Language/Language copy/_index.md b/userguide/content/en/docs/dev-test-content/Language/Language copy/_index.md new file mode 100644 index 0000000000..6c522471af --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Language/Language copy/_index.md @@ -0,0 +1,60 @@ +--- +title: "Multi-language Support" +linkTitle: "Multi-language Support" +weight: 7 +description: > + Support multiple languages in your site. +--- + +If you'd like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions. + +## Content and configuration + +To add content in multiple languages, you first need to define the available languages in a `languages` section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English: + +```toml +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +... +[languages] +[languages.en] +title = "Docsy" +description = "Docsy does docs" +languageName ="English" +# Weight used for sorting. +weight = 1 +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" +``` + +Any setting not defined in a `[languages]` block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be `content/en` unless the user selects the Norwegian language option. + +Once you've updated your site config, you create a content root directory for each language version in your source repo, such as `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information. + +{{% alert title="Tip" %}} +If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language. +{{% /alert %}} + +For adding multiple language versions of other site elements such as button text, see the [internationalization bundles](#internationalization-bundles) section below. + +## Selecting a language + +If you configure more than one language in `config.toml`, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language. + +## Internationalization bundles + +All UI strings (text for buttons etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. + +If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of `en.toml` called `jp.toml`), we recommend you do this **in the theme** rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project's `/i18n` folder. + +{{% alert title="Hugo Tip" %}} +Run `hugo server --i18n-warnings` when doing translation work, as it will give you warnings on what strings are missing. +{{% /alert %}} + + diff --git a/userguide/content/en/docs/dev-test-content/Language/_index.md b/userguide/content/en/docs/dev-test-content/Language/_index.md new file mode 100644 index 0000000000..b0a2a4fa83 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/Language/_index.md @@ -0,0 +1,61 @@ +--- +title: "Multi-language Support" +linkTitle: "Multi-language Support" +weight: 7 +icon: fas fa-globe +description: > + Support multiple languages in your site. +--- + +If you'd like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions. + +## Content and configuration + +To add content in multiple languages, you first need to define the available languages in a `languages` section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English: + +```toml +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +... +[languages] +[languages.en] +title = "Docsy" +description = "Docsy does docs" +languageName ="English" +# Weight used for sorting. +weight = 1 +[languages.no] +title = "Docsy" +description = "Docsy er operativsystem for skyen" +languageName ="Norsk" +contentDir = "content/no" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" +``` + +Any setting not defined in a `[languages]` block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be `content/en` unless the user selects the Norwegian language option. + +Once you've updated your site config, you create a content root directory for each language version in your source repo, such as `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information. + +{{% alert title="Tip" %}} +If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language. +{{% /alert %}} + +For adding multiple language versions of other site elements such as button text, see the [internationalization bundles](#internationalization-bundles) section below. + +## Selecting a language + +If you configure more than one language in `config.toml`, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language. + +## Internationalization bundles + +All UI strings (text for buttons etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. + +If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of `en.toml` called `jp.toml`), we recommend you do this **in the theme** rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project's `/i18n` folder. + +{{% alert title="Hugo Tip" %}} +Run `hugo server --i18n-warnings` when doing translation work, as it will give you warnings on what strings are missing. +{{% /alert %}} + + diff --git a/userguide/content/en/docs/dev-test-content/_index.md b/userguide/content/en/docs/dev-test-content/_index.md new file mode 100644 index 0000000000..0ce8b75460 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/_index.md @@ -0,0 +1,42 @@ +--- +title: "DEV Test Content" +weight: 2 +icon: fas fa-tools +tags: ["tag 1","tag 2","tag 3","a very long tag","atagwithaveryverylongword","atagwithaveryveryveryveryveryverylongword","one more long tag existing of more words","And another long tag existing of much more words, to see if the screen will explode, wenn it's really very very long","Testtag"] +projects: ["project 1","project 2","project 3"] +categories: ["category 1","category 2","category 3"] +text tags: ["simple text tag","another text tag","one more text tag"] +fruits: ["Apple","Carrot","Lemon"] +description: > + Some examples of Docsy in action! - I need a little bit more lead text: One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you’ve got a production site up and running with Docsy! +--- + +One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you've got a production site up and running with Docsy! + +## Docsy theme examples + +Example sites that have low to no customization: + +| Site | Repo (if public) | +|---|---| +| [This Docsy documentation site](/docs) | https://github.com/google/docsy | +| ["Goldydocs" - a Docsy example site](https://example.docsy.dev) | https://github.com/google/docsy-example | +| https://www.kubeflow.org/ | https://github.com/kubeflow/website | +| https://agones.dev/site/ | https://github.com/GoogleCloudPlatform/agones/tree/master/site | +| https://googlecontainertools.github.io/kpt/ | https://github.com/GoogleContainerTools/kpt/tree/master/docs | +| [Navidrome Music Server](https://www.navidrome.org) | https://github.com/navidrome/website | +| https://docs.agilebase.co.uk/ | https://github.com/okohll/abdocs | +| https://jvmperf.net/ | https://github.com/cchesser/java-perf-workshop | +| [gRPC](https://www.grpc.io/) | https://github.com/grpc/grpc.io + +## Customized Docsy examples + +Example sites that include a moderate to high amount of customization: + +| Site | Repo (if public) | +|---|---| +| [Knative](https://knative.dev) | https://github.com/knative/docs and https://github.com/knative/website | +| [Apache Airflow](https://airflow.apache.org/) | https://github.com/apache/airflow-site/ | +| [Docsy Just Docs](https://docsyjustdocs.netlify.com/) | https://github.com/LisaFC/justdocs | +| [Thunderhead Engineering Product Support](https://support.thunderheadeng.com/) | https://gitlab.com/tecidev/support (private) | +| [Kubernetes](https://kubernetes.io) | https://github.com/kubernetes/website | diff --git a/userguide/content/en/docs/dev-test-content/external-links/_index.md b/userguide/content/en/docs/dev-test-content/external-links/_index.md new file mode 100644 index 0000000000..6cea0f0699 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/external-links/_index.md @@ -0,0 +1,6 @@ +--- +title: "Manual Link" +weight: 1 +description: > + Some examples for manual links +--- diff --git a/userguide/content/en/docs/dev-test-content/external-links/external-link.md b/userguide/content/en/docs/dev-test-content/external-links/external-link.md new file mode 100644 index 0000000000..20b5be8ee8 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/external-links/external-link.md @@ -0,0 +1,13 @@ +--- +title: "external link" +linkTitle: "external link" +manualLink: "https://themes.gohugo.io/docsy/" +manualLinkTitle: "external link opens in new window or tab" +manualLinkTarget: "_blank" +type: docs +date: 2020-11-27T00:00:00+01:00 +draft: false +weight: 999 +description: > + External link to following page: [https://themes.gohugo.io/docsy/](https://themes.gohugo.io/docsy/ "external link") +--- \ No newline at end of file diff --git a/userguide/content/en/docs/dev-test-content/external-links/internal-link.md b/userguide/content/en/docs/dev-test-content/external-links/internal-link.md new file mode 100644 index 0000000000..daa1dc578f --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/external-links/internal-link.md @@ -0,0 +1,12 @@ +--- +title: "internal without relref" +linkTitle: "internal without relref" +manualLink: "/about/" +manualLinkTitle: "internal link to about page without using relref" +type: docs +date: 2020-11-27T00:00:00+01:00 +draft: false +weight: 999 +description: > + Internal link to following page: [about](/about/ "internal link") +--- \ No newline at end of file diff --git a/userguide/content/en/docs/dev-test-content/external-links/internal_link-relref.md b/userguide/content/en/docs/dev-test-content/external-links/internal_link-relref.md new file mode 100644 index 0000000000..18ddf47fa4 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/external-links/internal_link-relref.md @@ -0,0 +1,14 @@ +--- +title: "internal link with relref" +linkTitle: "internal link with relref" +manualLinkRelref: "about" +manualLinkTitle: "internal link to about page using relref" +type: docs +date: 2020-11-27T00:00:00+01:00 +draft: false +weight: 999 +description: > + Internal link to following page: [about]({{% relref "about" %}} "internal link") - The link in the page (which uses alsoe the relref function of Hugo) description doesn't render correct, because the page description get markdownified and markdownify doesn't replace shortcodes. +--- + +[about]({{< relref "about" >}} "internal link") diff --git a/userguide/content/en/docs/dev-test-content/external-links/url-link.md b/userguide/content/en/docs/dev-test-content/external-links/url-link.md new file mode 100644 index 0000000000..c7f12c6e90 --- /dev/null +++ b/userguide/content/en/docs/dev-test-content/external-links/url-link.md @@ -0,0 +1,11 @@ +--- +title: "Hugo like link via url parameter" +linkTitle: "url parameter" +url: "hugo-like-link" +type: docs +date: 2020-11-27T00:00:00+01:00 +draft: false +weight: 999 +description: > + Hugo like link via url parameter +--- \ No newline at end of file diff --git a/userguide/content/no/_index.html b/userguide/content/no/_index.html new file mode 100644 index 0000000000..19125eb6a4 --- /dev/null +++ b/userguide/content/no/_index.html @@ -0,0 +1,22 @@ ++++ +title = "TechOS" +linkTitle = "TechOS" + ++++ + +{{< blocks/cover title="Dette er TechOS!" image_anchor="top" height="full" >}} +
TechOS kan nå lastes ned i AppStore!
+