From 380102c6ef41b4b40cb4f34f9fa4b8496543418e Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 30 May 2021 15:59:13 +0200 Subject: [PATCH] Updated tags documentation --- docs/deprecations.md | 20 ++++++++++++++++---- docs/reference/meta-tags.md | 10 ++++++++-- docs/setup/adding-a-comment-system.md | 6 ++++-- docs/setup/setting-up-navigation.md | 7 ++++--- docs/setup/setting-up-site-search.md | 3 ++- docs/setup/setting-up-tags.md | 23 ++++++++++++++++++++++- 6 files changed, 56 insertions(+), 13 deletions(-) diff --git a/docs/deprecations.md b/docs/deprecations.md index 1f36a71e4..5fdeb3304 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -19,10 +19,13 @@ The `redirect` key, which could be added via [Metadata][1], allowed to specify a redirect from within a document to a new address, which is a good idea when moving content around: -``` markdown +``` bash --- redirect: /path/to/new/file --- + +# Document title +... ``` The [redirects][2] plugin provides the ability to define redirect mappings via @@ -54,11 +57,14 @@ The `source` and `path` keys, which could be added via [Metadata][1], showed a source icon at the top right corner of a document, linking a document to a single source file: -``` markdown +``` bash --- path: tree/master/docs source: deprecations.md --- + +# Document title +... ``` Only a single source file could be linked, which is useless if a document refers @@ -84,10 +90,13 @@ The `hero` key, which could be added via [Metadata][1], allowed to render a simple, text-only and page-local teaser text as part of a document. It could be set from front matter with: -``` markdown +``` bash --- hero: Lorem ipsum dolor sit amet --- + +# Document title +... ``` The recommended way is to [override the `hero` block][5] via [theme @@ -96,10 +105,13 @@ templates can be shared among multiple pages: === "Markdown" - ``` markdown + ``` bash --- template: hero.html --- + + # Document title + ... ``` === "Template" diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index fde01756c..30b90c990 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -38,10 +38,13 @@ Markdown document, delimited by a blank line which ends the YAML context. If the [Metadata][5] extension is enabled, the page title can be overridden on a per-document basis with custom front matter: -``` markdown +``` bash --- title: Lorem ipsum dolor sit amet --- + +# Document title +... ``` This will set the `title` tag inside the document `head` for the current page @@ -55,10 +58,13 @@ separator, which is the default behavior. If the [Metadata][5] extension is enabled, the page description can also be overridden on a per-document basis with custom front matter: -``` markdown +``` bash --- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. --- + +# Document title +... ``` This will set the `meta` tag containing the site description inside the diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 9e391d959..77c1e6430 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -46,21 +46,23 @@ specific pages by adding the following to the front matter of a page: === "Enable Disqus" - ``` yaml + ``` bash --- disqus: --- + # Document title ... ``` === "Disable Disqus" - ``` yaml + ``` bash --- disqus: "" --- + # Document title ... ``` diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 44be8eb0a..64f438bc3 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -388,13 +388,14 @@ Sometimes it's desirable to hide the navigation and/or table of contents sidebar, especially when there's a single navigation item. This can be done for any page using the [Metadata][29] extension: -``` yaml +``` bash --- hide: - - navigation # Hide navigation - - toc # Hide table of contents + - navigation + - toc --- +# Document title ... ``` diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index e9772ca79..f9e2141ae 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -273,12 +273,13 @@ In order to give specific pages a higher relevance in search, [lunr][4] supports page-specific boosts, which can be defined for each page by leveraging the [Metadata][19] extension: -``` yaml +``` bash --- search: boost: 100 --- +# Document title ... ``` diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 87782bb4b..45dd0eb3e 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -86,7 +86,7 @@ tags: ... ``` -The page will now render with those tags below the main headline and within the +The page will now render with those tags above the main headline and within the search preview, which now allows to __find pages by tags__, as shown in the following screenshots: @@ -125,3 +125,24 @@ arbitrary content before and after the marker: [8]: #tags_file [9]: ../assets/screenshots/tags-index.png + +### Hiding the tags + +[:octicons-file-code-24: Source][1] ยท +:octicons-note-24: Metadata + +While the tags are rendered above the main headline, sometimes, it might be +desirable to hide them for a specific page, which can be achieved by using the +[Metadata][10] extension: + +``` bash +--- +hide: + - tags +--- + +# Document title +... +``` + + [10]: ../../reference/meta-tags/#metadata