From d0cf645cf9c1e3b0584d6a0648b1218c836c017c Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Sat, 3 Feb 2024 23:30:57 +0100 Subject: [PATCH] user guide, definition listings of site params: add 'params' context (#1828) --- .../content/en/docs/adding-content/content.md | 26 ++++++---- .../en/docs/adding-content/iconsimages.md | 16 +++++-- .../en/docs/adding-content/lookandfeel.md | 10 +++- .../docs/adding-content/repository-links.md | 34 +++++++++---- .../content/en/docs/adding-content/search.md | 25 ++++++++-- .../en/docs/adding-content/versioning.md | 48 ++++++++++++++----- .../docs/get-started/basic-configuration.md | 5 +- 7 files changed, 119 insertions(+), 45 deletions(-) diff --git a/userguide/content/en/docs/adding-content/content.md b/userguide/content/en/docs/adding-content/content.md index ac2739011f..9c5d605050 100644 --- a/userguide/content/en/docs/adding-content/content.md +++ b/userguide/content/en/docs/adding-content/content.md @@ -614,17 +614,20 @@ Hugo will, by default, create an RSS feed for the home page and any section. For {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] rss_sections = ["blog"] {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -rss_sections: - - blog +params: + rss_sections: [blog] {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "rss_sections": [ - "blog" - ] + "params": { + "rss_sections": [ + "blog" + ] + } } {{< /tab >}} {{< /tabpane >}} @@ -634,17 +637,20 @@ To disable all RSS feeds, add the following to your `hugo.toml`/`hugo.yaml`/`hug {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] disableKinds = ["RSS"] {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -disableKinds: - - RSS +params: + disableKinds: [RSS] {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "disableKinds": [ - "RSS" - ] + "params": { + "disableKinds": [ + "RSS" + ] + } } {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md index 29dcdcd2d5..8feed7501e 100644 --- a/userguide/content/en/docs/adding-content/iconsimages.md +++ b/userguide/content/en/docs/adding-content/iconsimages.md @@ -11,20 +11,28 @@ By default, Docsy shows a site logo at the start of the navbar, that is, at the extreme left. Place your project's SVG logo in `assets/icons/logo.svg`. This overrides the default Docsy logo in the theme. -If you don't want a logo to appear in the navbar, then set `navbar_logo` to -`false` in your project's config: +If you don't want a logo to appear in the navbar, then set site parameter `navbar_logo` +to `false` in your project's config: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params.ui] navbar_logo = false {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -navbar_logo: false +params: + ui: + navbar_logo: false {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} + { - "navbar_logo": false + "params": { + "ui": { + "navbar_logo": false + } + } } {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index e64509ab03..f670887f06 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -158,14 +158,20 @@ Optionally, you can enable Prism syntax highlighting in your `hugo.toml`/`hugo.y {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] # Enable syntax highlighting and copy buttons on code blocks with Prism prism_syntax_highlighting = true {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -prism_syntax_highlighting: true +params: + prism_syntax_highlighting: true {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"prism_syntax_highlighting": true +{ + "params": { + "prism_syntax_highlighting": true + } +} {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/adding-content/repository-links.md b/userguide/content/en/docs/adding-content/repository-links.md index 685114ed67..5a9a7cd17c 100644 --- a/userguide/content/en/docs/adding-content/repository-links.md +++ b/userguide/content/en/docs/adding-content/repository-links.md @@ -18,7 +18,7 @@ Currently, Docsy supports only GitHub repository links "out of the box". Since G ## Link configuration -There are four variables you can configure in `hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as one in your page metadata. +There are four site variables you can configure in `hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as one in your page metadata. ### `github_repo` @@ -27,14 +27,18 @@ The URL for your site's source repository. This is used to generate the **Edit t {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] github_repo = "https://github.com/google/docsy" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -github_repo: 'https://github.com/google/docsy' +params: + github_repo: https://github.com/google/docsy {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "github_repo": "https://github.com/google/docsy" + "params": { + "github_repo": "https://github.com/google/docsy" + } } {{< /tab >}} {{< /tabpane >}} @@ -46,14 +50,18 @@ Specify a value here if your content directory is not in your repo's root direct {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] github_subdir = "userguide" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -github_subdir: 'userguide' +params: + github_subdir: userguide {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "github_subdir": "userguide" + "params": { + "github_subdir": "userguide" + } } {{< /tab >}} {{< /tabpane >}} @@ -65,14 +73,18 @@ Specify a value here if you have a separate project repo and you'd like your use {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] github_project_repo = "https://github.com/google/docsy" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -github_project_repo: 'https://github.com/google/docsy' +params: + github_project_repo: https://github.com/google/docsy {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "github_project_repo": "https://github.com/google/docsy" + "params": { + "github_project_repo": "https://github.com/google/docsy" + } } {{< /tab >}} {{< /tabpane >}} @@ -84,14 +96,18 @@ Specify a value here if you have would like to reference a different branch for {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] github_branch = "release" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -github_branch: 'release' +params: + github_branch: release {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "github_branch": "release" + "params": { + "github_branch": "release" + } } {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/adding-content/search.md b/userguide/content/en/docs/adding-content/search.md index 62c020f0f0..09d1326099 100644 --- a/userguide/content/en/docs/adding-content/search.md +++ b/userguide/content/en/docs/adding-content/search.md @@ -24,18 +24,28 @@ behavior when serving your site. ## Disabling the sidebar search box -By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don't want the sidebar search box, set `sidebar_search_disable` to `true` in `hugo.toml`/`hugo.yaml`/`hugo.json`: +By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don't want the sidebar search box, set the site parameter `sidebar_search_disable` to `true` in `hugo.toml`/`hugo.yaml`/`hugo.json`: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params.ui] sidebar_search_disable = true {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -sidebar_search_disable: true +params: + ui: + sidebar_search_disable: true {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"sidebar_search_disable": true +{ + "params": { + "ui": { + "sidebar_search_disable": true + } + } +} + {{< /tab >}} {{< /tabpane >}} @@ -88,14 +98,19 @@ layout: search {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] +# Google Custom Search Engine ID. Remove or comment out to disable search. gcs_engine_id = "011737558837375720776:fsdu1nryfng" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -gcs_engine_id: '011737558837375720776:fsdu1nryfng' +params: + gcs_engine_id: 011737558837375720776:fsdu1nryfng {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "gcs_engine_id": "011737558837375720776:fsdu1nryfng" + "params": { + "gcs_engine_id": "011737558837375720776:fsdu1nryfng" + } } {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/adding-content/versioning.md b/userguide/content/en/docs/adding-content/versioning.md index 58c91d0c84..a7852d75a8 100644 --- a/userguide/content/en/docs/adding-content/versioning.md +++ b/userguide/content/en/docs/adding-content/versioning.md @@ -69,18 +69,24 @@ params: Remember to add your current version so that users can navigate back! The default title for the version drop-down menu is **Releases**. To change the -title, change the `version_menu` parameter in `hugo.toml`/`hugo.yaml`/`hugo.json`: +title, change the site parameter `version_menu` in `hugo.toml`/`hugo.yaml`/`hugo.json`: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] version_menu = "Releases" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -version_menu: 'Releases' +params: + version_menu: Releases {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"version_menu": "Releases" +{ + "params": { + "version_menu": "Releases" + } +} {{< /tab >}} {{< /tabpane >}} @@ -113,50 +119,68 @@ For example, see the archived docs for To add the banner to your doc site, make the following changes in your `hugo.toml`/`hugo.yaml`/`hugo.json` file: -1. Set the `archived_version` parameter to `true`: +1. Set the site parameter `archived_version` to `true`: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] archived_version = true {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -archived_version: true +params: + archived_version: true {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"archived_version": true +{ + "params": { + "archived_version": true + } +} {{< /tab >}} {{< /tabpane >}} -1. Set the `version` parameter to the version of the archived doc set. For +1. Set the site parameter `version` to the version of the archived doc set. For example, if the archived docs are for version 0.1: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] version = "0.1" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -version: '0.1' +params: + version: 0.1 {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"version": "0.1" +{ + "params": { + "version": "0.1" + } +} {{< /tab >}} {{< /tabpane >}} -1. Make sure that `url_latest_version` contains the URL of the website that you +1. Make sure that site parameter `url_latest_version` contains the URL of the website that you want to point readers to. In most cases, this should be the URL of the latest version of your docs: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} +[params] url_latest_version = "https://your-latest-doc-site.com" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -url_latest_version: 'https://your-latest-doc-site.com' +params: + url_latest_version: https://your-latest-doc-site.com {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} -"url_latest_version": "https://your-latest-doc-site.com" +{ + "params": { + "url_latest_version": "https://your-latest-doc-site.com" + } +} {{< /tab >}} {{< /tabpane >}} diff --git a/userguide/content/en/docs/get-started/basic-configuration.md b/userguide/content/en/docs/get-started/basic-configuration.md index a84232500c..dc8125c274 100644 --- a/userguide/content/en/docs/get-started/basic-configuration.md +++ b/userguide/content/en/docs/get-started/basic-configuration.md @@ -43,11 +43,10 @@ By default, the Docsy example site uses its own [Google Custom Search Engine](ht ``` # Google Custom Search Engine ID. Remove or comment out to disable search. -gcs_engine_id = "011737558837375720776:fsdu1nryfng" +gcs_engine_id = "..." ``` -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/search). - +To use your own Custom Search Engine, set `gcs_engine_id` to your search engine ID. For details, see [Configure search with a Google Custom Search Engine](/docs/adding-content/search/#configure-search-with-a-google-custom-search-engine). ## What's next?