Updated tags documentation

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"

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

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: <shortname>
     ---
 
+    # Document title
     ...
     ```
 
 === "Disable Disqus"
 
-    ``` yaml
+    ``` bash
     ---
     disqus: ""
     ---
 
+    # Document title
     ...
     ```
 

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
 ...
 ```
 

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
 ...
 ```
 

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