Documentation

docs/reference/index.md

@@ -5,7 +5,7 @@ template: overrides/main.html
 # Reference
 
 Material for MkDocs is packed with many great features that make technical
-writing a pleasure. This section of the documentation explains how to set up
+writing a joyful activity. This section of the documentation explains how to set up
 a page, and showcases all available specimen that can be used directly from
 within Markdown files.
 
@@ -55,8 +55,10 @@ The following configuration options are available:
 
 ### Setting the page title
 
-The page title can be overridden for a document with the front matter `title`
-property. Add the following lines at the top of a Markdown file:
+Each page has a designated title, which is used in the navigation sidebar, for 
+[social cards] and in other places. While MkDocs attempts to automatically 
+determine the title of a page in a [four step process], the title can also be 
+explicitly set with the front matter `title` property:
 
 ``` yaml
 ---
@@ -67,18 +69,23 @@ title: Lorem ipsum dolor sit amet # (1)!
 ...
 ```
 
-1.  This will set the [`title`][title] inside the HTML document's [`head`][head]
-    for the generated page to this value. Note that the site title, which is set
-    via [`site_name`][site_name], is appended with a dash.
+1.  This line sets the [`title`][title] inside the HTML document's
+    [`head`][head] for the generated page to the given value. Note that the
+    site title, which is set via [`site_name`][site_name], is appended with a
+    dash.
 
+  [social cards]: ../setup/setting-up-social-cards.md
+  [four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
   [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
   [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
   [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
 
 ### Setting the page description
 
-The page description can be overridden for a document with the front matter
-`description` property. Add the following lines at the top of a Markdown file:
+A Markdown file can include a description that is added to the `meta` tags of
+a page, and is also used for [social cards]. It's a good idea to set a 
+[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
+the author does not explicitly define a description for a Markdown file:
 
 ``` yaml
 ---
@@ -89,9 +96,11 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 ...
 ```
 
-1.  This will set the `meta` tag containing the site description inside the
+1.  This line sets the `meta` tag containing the description inside the
     document `head` for the current page to the provided value.
 
+  [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+
 ### Setting the page icon
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
@@ -99,7 +108,9 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 :octicons-beaker-24: Experimental
 
 An icon can be assigned to each page, which is then rendered as part of the
-navigation sidebar. Add the following lines at the top of a Markdown file:
+navigation sidebar, as well as [navigation tabs], if enabled. Use the front
+matter `icon` property to reference an icon, adding the following lines at the
+top of a Markdown file:
 
 ``` yaml
 ---
@@ -123,6 +134,7 @@ icon: material/emoticon-happy # (1)!
 
   [Insiders]: ../insiders/index.md
   [icon search]: icons-emojis.md#search
+  [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
 
 ### Setting the page status
 
@@ -150,9 +162,9 @@ extra:
         new: Recently added
     ```
 
-The page status can now be set for a document with the front matter `status`
-property. For example, you can mark a page as `new` with the following lines at 
-the top of a Markdown file:
+The page status can now be set with the front matter `status` property. For
+example, you can mark a page as `new` with the following lines at the top of a 
+Markdown file:
 
 ``` yaml
 ---
@@ -168,6 +180,25 @@ The following status identifiers are currently supported:
 - :material-alert-decagram: – `new`
 - :material-trash-can: – `deprecated`
 
+### Setting the page subtitle
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.25.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Each page can define a subtitle, which is then rendered below the title as part
+of the navigation sidebar by using the front matter `subtitle` property, and
+adding the following lines:
+
+``` yaml
+---
+subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
+---
+
+# Document title
+...
+```
+
 ### Setting the page template
 
 If you're using [theme extension] and created a new page template in the