Documentation

docs/creating-your-site.md

@@ -100,11 +100,12 @@ and much more:
 - [Setting up navigation][9]
 - [Setting up site search][10]
 - [Setting up site analytics][11]
-- [Setting up versioning][12]
+- [Setting up tags][12]
-- [Setting up the header][13]
+- [Setting up versioning][13]
-- [Setting up the footer][14]
+- [Setting up the header][14]
-- [Adding a git repository][15]
+- [Setting up the footer][15]
-- [Adding a comment system][16]
+- [Adding a git repository][16]
+- [Adding a comment system][17]
 
 </div>
 
@@ -115,11 +116,12 @@ and much more:
   [9]: setup/setting-up-navigation.md
   [10]: setup/setting-up-site-search.md
   [11]: setup/setting-up-site-analytics.md
-  [12]: setup/setting-up-versioning.md
+  [12]: setup/setting-up-tags.md
-  [13]: setup/setting-up-the-header.md
+  [13]: setup/setting-up-versioning.md
-  [14]: setup/setting-up-the-footer.md
+  [14]: setup/setting-up-the-header.md
-  [15]: setup/adding-a-git-repository.md
+  [15]: setup/setting-up-the-footer.md
-  [16]: setup/adding-a-comment-system.md
+  [16]: setup/adding-a-git-repository.md
+  [17]: setup/adding-a-comment-system.md
 
 ## Previewing as you write
 
@@ -145,12 +147,12 @@ If you're running Material for MkDocs from within Docker, use:
     docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
     ```
 
-Point your browser to [localhost:8000][17] and you should see:
+Point your browser to [localhost:8000][18] and you should see:
 
-[![Creating your site][18]][18]
+[![Creating your site][19]][19]
 
-  [17]: http://localhost:8000
+  [18]: http://localhost:8000
-  [18]: assets/screenshots/creating-your-site.png
+  [19]: assets/screenshots/creating-your-site.png
 
 ## Building your site
 
@@ -163,8 +165,8 @@ mkdocs build
 
 The contents of this directory make up your project documentation. There's no
 need for operating a database or server, as it is completely self-contained.
-The site can be hosted on [GitHub Pages][19], [GitLab Pages][20], a CDN of your
+The site can be hosted on [GitHub Pages][20], [GitLab Pages][21], a CDN of your
 choice or your private web space.
 
-  [19]: publishing-your-site.md#github-pages
+  [20]: publishing-your-site.md#github-pages
-  [20]: publishing-your-site.md#gitlab-pages
+  [21]: publishing-your-site.md#gitlab-pages

docs/customization.md

@@ -152,7 +152,7 @@ directory:
 MkDocs will now use the new partial when rendering the theme. This can be done
 with any file.
 
-### Overriding blocks
+### Overriding blocks <small>recommended</small> { data-toc-label="Overiding blocks" }
 
 Besides overriding partials, it's also possible to override (and extend)
 _template blocks_, which are defined inside the templates and wrap specific
@@ -273,7 +273,7 @@ Start the watcher with:
 npm start
 ```
 
-Then, in a second session, start the MkDocs server with:
+Then, in a second session, start the MkDocs live preview server with:
 
 ```
 mkdocs serve

docs/data-privacy.md

@@ -4,9 +4,9 @@ template: overrides/main.html
 
 # Data privacy
 
-In itself, Material for MkDocs does not perform any tracking and should adhere
+In itself, Material for MkDocs does not perform any tracking and adheres to the
-to the [General Data Protection Regulation][1] (GDPR), but it integrates with
+[General Data Protection Regulation][1] (GDPR), but it integrates with some
-some third-party services that may not.
+third-party services that may not.
 
   [1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
 
@@ -15,7 +15,7 @@ some third-party services that may not.
 ### Google Fonts
 
 Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
-CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily 
+CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
 disabled][3] via `mkdocs.yml`.
 
   [2]: setup/changing-the-fonts.md
@@ -23,7 +23,7 @@ disabled][3] via `mkdocs.yml`.
 
 ### Google Analytics and Disqus
 
-Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] 
+Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
 integrations, both of which must be enabled explicitly, so there's no immediate
 action if you don't use those.
 

docs/deprecations.md

@@ -112,7 +112,7 @@ templates can be shared among multiple pages:
     {% endblock %}
     ```
 
-  [5]: customization.md#overriding-blocks
+  [5]: customization.md#overriding-blocks-recommended
   [6]: customization.md#extending-the-theme
 
 ## Docker image

docs/getting-started.md

@@ -13,13 +13,13 @@ If not, we recommended using [`docker`][3].
 In case you're running into problems, consult the [troubleshooting][4] section.
 
   [1]: https://www.mkdocs.org
-  [2]: #with-pip
+  [2]: #with-pip-recommended
   [3]: #with-docker
   [4]: troubleshooting.md
 
 ## Installation
 
-### with pip
+### with pip <small>recommended</small> { data-toc-label="with pip" }
 
 Material for MkDocs can be installed with `pip`:
 

docs/insiders/getting-started.md

@@ -11,7 +11,7 @@ Material for MkDocs, and can be installed similar to the public version using
 account is added to the list of collaborators of the private Insiders
 repository.
 
-  [1]: #with-pip
+  [1]: #with-pip-recommended
   [2]: #with-docker
   [3]: #with-git
 

docs/reference/meta-tags.md

@@ -94,7 +94,7 @@ policies for search engines:
 ```
 
   [7]: ../customization.md#extending-the-theme
-  [8]: ../customization.md#overriding-blocks
+  [8]: ../customization.md#overriding-blocks-recommended
 
 #### on a single page
 

docs/setup/adding-a-comment-system.md

@@ -82,4 +82,4 @@ In order to integrate another JavaScript-based comment system provider, you can
 
   [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
   [7]: ../customization.md#extending-the-theme
-  [8]: ../customization.md#overriding-blocks
+  [8]: ../customization.md#overriding-blocks-recommended

docs/setup/changing-the-fonts.md

@@ -109,5 +109,5 @@ fonts being added automatically):
 
   [5]: ../data-privacy.md
   [6]: ../customization.md#extending-the-theme
-  [7]: ../customization.md#overriding-blocks
+  [7]: ../customization.md#overriding-blocks-recommended
   [8]: ../customization.md#additional-stylesheets

docs/setup/setting-up-site-analytics.md

@@ -7,7 +7,7 @@ template: overrides/main.html
 As with any other service offered on the web, understanding how your project
 documentation is actually used can be an essential success factor. While
 Material for MkDocs natively integrates with [Google Analytics][1], [other
-analytics services][2] can be used, too.
+analytics providers][2] can be used, too.
 
   [1]: https://developers.google.com/analytics
   [2]: #other-analytics-providers
@@ -61,7 +61,7 @@ and [override the `analytics` block][6]:
 ```
 
   [5]: ../customization.md#extending-the-theme
-  [6]: ../customization.md#overriding-blocks
+  [6]: ../customization.md#overriding-blocks-recommended
 
 If you're using [instant loading][7], you may use the `location$` observable,
 which will emit the current `URL` to listen for navigation events and register

docs/setup/setting-up-site-search.md

@@ -315,9 +315,9 @@ export function defaultTransform(query: string): string {
 }
 ```
 
-If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
+If you want to switch to the default behavior of the `mkdocs` and `readthedocs`
-template, both of which don't transform the query prior to submission, or
+themes, both of which don't transform the query prior to submission, or
-customize the `transform` function, you can do this by [overriding the 
+customize the `transform` function, you can do this by [overriding the
 `config` block][21]:
 
 ``` html
@@ -338,7 +338,7 @@ and must return the processed query string to be submitted to the search index.
 
   [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
   [20]: ../customization.md#extending-the-theme
-  [21]: ../customization.md#overriding-blocks
+  [21]: ../customization.md#overriding-blocks-recommended
 
 ### Custom search
 
@@ -361,10 +361,10 @@ directory and [override the `config` block][21]:
 {% endblock %}
 ```
 
-Communication with the search worker is implemented using a standardized
+Communication with the search worker is implemented using a designated message
-message format using _discriminated unions_, i.e. through the `type` property
+format using _discriminated unions_, i.e. through the `type` property of the
-of the message. See the following interface definitions to learn about the
+message. See the following interface definitions to learn about the message
-message formats:
+formats:
 
 - [:octicons-file-code-24: `SearchMessage`][24]
 - [:octicons-file-code-24: `SearchIndex` and `SearchResult`][25]

docs/setup/setting-up-tags.md

@@ -72,8 +72,8 @@ The following options are available:
 [:octicons-file-code-24: Source][1] ·
 :octicons-note-24: Metadata
 
-If the [built-in tags plugin][4] and [Metadata][5] extension are enabled, tags
+If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled,
-can be added for any page as part of the front matter, e.g. to add the tags 
+tags can be added for any page as part of the front matter, e.g. to add the tags
 `insiders` and `brand new` to this page, add:
 
 ``` yaml
@@ -87,7 +87,7 @@ tags:
 ```
 
 The page will now render with those tags below the main headline and within the
-search preview, which now allows to __search for tags__, as shown in the
+search preview, which now allows to __find pages by tags__, as shown in the
 following screenshots:
 
 === "Tags"

docs/setup/setting-up-the-header.md

@@ -48,4 +48,4 @@ block][5], which is empty by default:
 ```
 
   [4]: ../customization.md#extending-the-theme
-  [5]: ../customization.md#overriding-blocks
+  [5]: ../customization.md#overriding-blocks-recommended

docs/setup/setting-up-versioning.md

@@ -102,7 +102,7 @@ Make sure that this matches the [default version][11].
 
   [7]: ../insiders/index.md
   [8]: ../customization.md#extending-the-theme
-  [9]: ../customization.md#overriding-blocks
+  [9]: ../customization.md#overriding-blocks-recommended
   [10]: ../assets/screenshots/version-warning.png
   [11]: #setting-a-default-version
 

docs/troubleshooting.md

@@ -113,5 +113,5 @@ of which is to use virtual environments:
     ```
 
   [1]: https://docs.python.org/3/tutorial/venv.html
-  [2]: getting-started.md#with-pip
+  [2]: getting-started.md#with-pip-recommended
   [3]: https://brew.sh/