Restructured documentation (#5692)

Author: squidfunk

.editorconfig

@@ -30,10 +30,6 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-# Markdown
-[*.md]
-trim_trailing_whitespace = false
-
 # Python
 [*.py]
 indent_style = space

Dockerfile

@@ -60,11 +60,8 @@ RUN \
   pip install --no-cache-dir . \
 && \
   if [ "${WITH_PLUGINS}" = "true" ]; then \
-    pip install --no-cache-dir \
-      "mkdocs-minify-plugin~=0.7" \
-      "mkdocs-redirects~=1.2" \
-      "pillow~=9.4" \
-      "cairosvg~=2.6"; \
+    pip install --no-cache-dir mkdocs-material[recommended] \
+    pip install --no-cache-dir mkdocs-material[imaging]; \
   fi \
 && \
   if [ -e user-requirements.txt ]; then \

docs/blog/posts/blog-support-just-landed.md

@@ -168,9 +168,9 @@ In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
 tellus id elit ultricies, vel finibus erat cursus.
 ```
 
-1.  If you mark a post as a [draft], a red marker appears next to the post date 
-    on index pages. When the site is built, drafts are not included in the 
-    output. [This behavior can be changed], e.g. for rendering drafts when 
+1.  If you mark a post as a [draft], a red marker appears next to the post date
+    on index pages. When the site is built, drafts are not included in the
+    output. [This behavior can be changed], e.g. for rendering drafts when
     building deploy previews.
 
 When you spin up the [live preview server], you should be greeted by your first
@@ -233,7 +233,7 @@ Some ideas already proposed by users:
   part of a series, a list with links to all other posts should be included in
   the post's content.
 
-- __Author indexes__: Besides [archive] and [category] indexes, authors should 
+- __Author indexes__: Besides [archive] and [category] indexes, authors should
   be able to create per-author indexes, which list all posts linked to an
   author. Additionally, a profile should be created for each author and linked
   from posts.

docs/blog/posts/chinese-search-support.md

@@ -3,25 +3,25 @@ date: 2022-05-05
 authors: [squidfunk]
 title: Chinese search support
 description: >
-  Insiders adds Chinese language support for the built-in search plugin – a 
+  Insiders adds Chinese language support for the built-in search plugin – a
   feature that has been requested many times
 categories:
   - Search
 links:
   - blog/posts/search-better-faster-smaller.md
-  - setup/setting-up-site-search.md#chinese-language-support
+  - plugins/search.md#segmentation
   - insiders/index.md#how-to-become-a-sponsor
 ---
 
 # Chinese search support – 中文搜索​支持
 
-__Insiders adds experimental Chinese language support for the [built-in search 
+__Insiders adds experimental Chinese language support for the [built-in search
 plugin] – a feature that has been requested for a long time given the large
 number of Chinese users.__
 
 After the United States and Germany, the third-largest country of origin of
 Material for MkDocs users is China. For a long time, the [built-in search plugin]
-didn't allow for proper segmentation of Chinese characters, mainly due to 
+didn't allow for proper segmentation of Chinese characters, mainly due to
 missing support in [lunr-languages] which is used for search tokenization and
 stemming. The latest Insiders release adds long-awaited Chinese language support
 for the built-in search plugin, something that has been requested by many users.
@@ -49,8 +49,8 @@ through the segmenter. You can install [jieba] with:
 pip install jieba
 ```
 
-The next step is only required if you specified the [`separator`][separator] 
-configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace] 
+The next step is only required if you specified the [`separator`][separator]
+configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace]
 characters, so it renders exactly the same in the search modal. Adjust
 `mkdocs.yml` so that the [`separator`][separator] includes the `\u200b`
 character:
@@ -65,14 +65,14 @@ That's all that is necessary.
 
 ## Usage
 
-If you followed the instructions in the configuration guide, Chinese words will 
+If you followed the instructions in the configuration guide, Chinese words will
 now be tokenized using [jieba]. Try searching for
-[:octicons-search-24: 支持][q=支持] to see how it integrates with the 
+[:octicons-search-24: 支持][q=支持] to see how it integrates with the
 built-in search plugin.
 
 ---
 
-Note that this is an experimental feature, and I, @squidfunk, am not 
+Note that this is an experimental feature, and I, @squidfunk, am not
 proficient in Chinese (yet?). If you find a bug or think something can be
 improved, please [open an issue].
 

docs/blog/posts/excluding-content-from-search.md

@@ -119,7 +119,7 @@ search:
   exclude: true
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -133,7 +133,7 @@ filtered by the search plugin before the page is rendered:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     ## Section 1
 
@@ -173,7 +173,7 @@ supported by the [Attribute Lists] extension:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     The content of this block is included
 

docs/blog/posts/search-better-faster-smaller.md

@@ -176,10 +176,10 @@ which creates and manages the [lunr] search index. When search is initialized,
 the following steps are taken:
 
   [^1]:
-    Prior to :octicons-tag-24: 5.0.0, search was carried out in the main thread 
-    which locked up the browser, rendering it unusable. This problem was first
-    reported in #904 and, after some back and forth, fixed and released in
-    :octicons-tag-24: 5.0.0.
+    Prior to <!-- md:version 5.0.0 -->, search was carried out in the main
+    thread  which locked up the browser, rendering it unusable. This problem was
+    first reported in #904 and, after some back and forth, fixed and released in
+    <!-- md:version 5.0.0 -->.
 
 1.  __Linking sections with pages__: The search index is parsed, and each
     section is linked to its parent page. The parent page itself is _not
@@ -196,7 +196,7 @@ the following steps are taken:
     > can achieve with a tokenizer that is capable of separating strings with
     > lookahead.
 
-1.  __Indexing__: As a final step, each section is indexed. When querying the
+3.  __Indexing__: As a final step, each section is indexed. When querying the
     index, if a search query includes one of the tokens as returned by step 2.,
     the section is considered to be part of the search result and passed to the
     main thread.

docs/browser-support.md

@@ -64,6 +64,4 @@ the following older browser versions might work with some additional effort:
 - :fontawesome-brands-internet-explorer: __Internet Explorer__ - no support,
   mainly due to missing support for [custom properties]. The last version of
   Material for MkDocs to support Internet Explorer is
-  [:octicons-tag-24: 4.6.3][IE support].
-
-  [IE support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.3
+  <!-- md:version 4.6.3 -->.

docs/contributing/reporting-a-bug.md

@@ -148,7 +148,7 @@ summary of the issue, so the impact and severity of the bug you want to report
 can be inferred from the title.
 
 | <!-- --> | Example  |
-| -------- | -------- | 
+| -------- | -------- |
 | :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
 | :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
 | :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
@@ -235,17 +235,17 @@ make it easier for us maintainers to improve the documentation.
 ### Reproduction
 
 A minimal reproduction is at the heart of every well-written bug report, as
-it allows us maintainers to quickly recreate the necessary conditions to inspect
-the bug and quickly find its root cause. It's a proven fact that issues with
-concise and small reproductions can be fixed much faster.
+it allows us maintainers to instantly recreate the necessary conditions to
+inspect the bug to quickly find its root cause. It's a proven fact that issues
+with concise and small reproductions can be fixed much faster.
 
 [:material-bug:&nbsp; Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
 
 ---
 
-After you have created the reproduction, you should have a .zip file, ideally not
-larger than 1 MB. Just drag and drop the .zip file into this field, which will
-automatically upload it to GitHub.
+After you have created the reproduction, you should have a `.zip` file, ideally
+not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
+will automatically upload it to GitHub.
 
 > __Why we need this__: if an issue contains no minimal reproduction or just
 > a link to a repository with thousands of files, the maintainers would need to
@@ -259,7 +259,7 @@ automatically upload it to GitHub.
     process. The reason is that the reproduction which is automatically
     produced by the [built-in info plugin] contains all of the necessary
     environment information that is often forgotten to be included.
-    
+
     Additionally, there are many non-technical users of Material for MkDocs that
     have trouble creating repositories.
 
@@ -301,7 +301,7 @@ only relevant when the bug you are reporting does not involve a crash when
 
 Thanks for following the guide and creating a high-quality and complete bug
 report – you are almost done. This section ensures that you have read this guide
-and have worked to the best of your knowledge to provide us with everything we 
+and have worked to the best of your knowledge to provide us with everything we
 need to know to help you.
 
 __We'll take it from here.__

docs/conventions.md

@@ -0,0 +1,67 @@
+# Conventions
+
+This section explains several conventions used in this documentation.
+
+## Symbols
+
+This documentation use some symbols for illustration purposes. Before you read
+on, please make sure you've made yourself familiar with the following list of
+conventions:
+
+### <!-- md:sponsors --> – Sponsors only { data-toc-label="Sponsors only" }
+
+The pumping heart symbol denotes that a specific feature or behavior is only
+available to sponsors via [Insiders]. Make sure that you have access to
+[Insiders] if you want to use the feature.
+
+### <!-- md:version --> – Version { data-toc-label="Version" }
+
+The tag symbol in conjunction with a version number denotes when a specific
+feature or behavior was added. Make sure you're at least on this version
+if you want to use it.
+
+### <!-- md:version insiders- --> – Version (Insiders)  { data-toc-label="Version (Insiders)" }
+
+The tag symbol with a heart in conjunction with a version number denotes that a
+specific feature or behavior was added to the [Insiders] version of Material for
+MkDocs.
+
+### <!-- md:default --> – Default value { #default data-toc-label="Default value" }
+
+Some properties in `mkdocs.yml` have default values for when the author does not
+explicitly define them. The default value of the property is always included.
+
+#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
+
+Some default values are not set to static values but computed form other values,
+like the site language, repository provider, or other settings.
+
+#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }
+
+Some properties do not contain default values. This means that the functionality
+that is associated with them is not available unless explicitly enabled.
+
+### <!-- md:feature --> – Optional feature { #feature data-toc-label="Optional feature" }
+
+Most of the features are hidden behind feature flags, which means they must
+be explicitly enabled via `mkdocs.yml`. This allows for the existence of
+potentially orthogonal features.
+
+### <!-- md:flag experimental --> – Experimental { data-toc-label="Experimental" }
+
+Some newer features are still considered experimental, which means the ymight
+(although rarely) change at any time, including their complete removal (which
+hasn't happened yet).
+
+### <!-- md:plugin --> – Plugin { data-toc-label="Plugin" }
+
+Several features are implemented through MkDocs excellent plugin architecture,
+some of which are built-in and distributed with Material for MkDocs, so no
+installation is required.
+
+### <!-- md:utility --> – Utility { data-toc-label="Utility" }
+
+Besides plugins, there are some utilities that build on top of MkDocs in order
+to provide extended functionality, like for example support for versioning.
+
+  [Insiders]: insiders/index.md

docs/creating-your-site.md

@@ -1,6 +1,6 @@
 # Creating your site
 
-After you've [installed] Material for MkDocs, you can bootstrap your project 
+After you've [installed] Material for MkDocs, you can bootstrap your project
 documentation using the `mkdocs` executable. Go to the directory where you want
 your project to be located and enter:
 
@@ -48,7 +48,7 @@ theme:
 
 ???+ tip "Recommended: [configuration validation and auto-complete]"
 
-    In order to minimize friction and maximize productivity, Material for MkDocs 
+    In order to minimize friction and maximize productivity, Material for MkDocs
     provides its own [schema.json][^1] for `mkdocs.yml`. If your editor supports
     YAML schema validation, it's definitely recommended to set it up: