Added back changelog and upgrade instructions

docs/changelog.md

@@ -2,21 +2,9 @@
 template: overrides/main.html
 ---
 
-# Upgrading
+# Changelog
 
-To upgrade to the latest version:
+## Release notes
-
-``` sh
-pip install --upgrade mkdocs-material
-```
-
-To inspect the currently installed version:
-
-``` sh
-pip show mkdocs-material
-```
-
-## Changelog
 
 ### 5.4.0 <small>_ June 29, 2020</small>
 

docs/contributing.md

@@ -1,5 +0,0 @@
----
-template: overrides/main.html
----
-
---8<-- "CONTRIBUTING.md"

docs/creating-your-site.md

@@ -71,10 +71,10 @@ icons and much more:
 * [Setting up navigation][7]
 * [Setting up site search][8]
 * [Setting up site analytics][9]
-* [Adding a git repository][10]
+* [Adding social links][10]
-* [Adding social links][11]
+* [Adding a git repository][11]
 * [Adding a comment system][12]
-* [Adding an announcement bar][13]
+<!-- * [Adding an announcement bar][13] -->
 <!-- * [Adding a landing page][14] -->
 
   [2]: getting-started.md#installation
@@ -85,10 +85,10 @@ icons and much more:
   [7]: setup/setting-up-navigation.md
   [8]: setup/setting-up-site-search.md
   [9]: setup/setting-up-site-analytics.md
-  [10]: setup/adding-a-git-repository.md
+  [10]: setup/adding-social-links.md
-  [11]: setup/adding-social-links.md
+  [11]: setup/adding-a-git-repository.md
   [12]: setup/adding-a-comment-system.md
-  [13]: setup/adding-an-announcement-bar.md
+  <!-- [13]: setup/adding-an-announcement-bar.md -->
   <!--[14]: setup/adding-a-landing-page.md-->
 
 ## Previewing as you write

docs/reference/meta-tags.md

@@ -0,0 +1,34 @@
+---
+template: overrides/main.html
+---
+
+# Meta tags
+
+TBD
+
+<!-- Material for MkDocs supports several flavors of lists that cater to different
+use cases, including _unordered lists_ and _ordered lists_, which are supported
+through standard Markdown, as well as _definition lists_ and _task lists_, which
+are supported through extensions. -->
+
+## Configuration
+
+### Metadata
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Metadata][1] extension, which is part of the standard Markdown
+library, adds the ability to add custom metadata to a document and can be 
+enabled from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - meta
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [2]: https://python-markdown.github.io/extensions/meta_data/
+
+## Customization
+
+- add custom meta tags, like twitter cards etc via customization!?

docs/releases/4.md

@@ -1,30 +0,0 @@
----
-template: overrides/main.html
----
-
-# Upgrading to 4.x
-
-## Highlights
-
-Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
-includes a mandatory change of the base font-size from `10px` to `20px` which
-means all `rem` values needed to be updated. Within the theme, `px` to `rem` 
-calculation is now encapsulated in a new function called `px2rem` which is part
-of the SASS code base.
-
-If you use Material for MkDocs with custom CSS that is based on `rem` values,
-note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
-`10px`, but `20px`. To learn more about the problem and implications, please
-refer to [the issue][1] in which the problem was discovered and fixed.
-
-  [1]: https://github.com/squidfunk/mkdocs-material/issues/911
-
-## How to upgrade
-
-### Changes to `mkdocs.yml`
-
-None.
-
-### Changes to `*.html` files
-
-None.

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

@@ -1,3 +1,7 @@
+---
+template: overrides/main.html
+---
+
 # Adding a comment system
 
 Material for MkDocs is natively integrated with [Disqus][1], a comment system
@@ -9,10 +13,43 @@ integrated, too.
 
 ## Configuration
 
-### Comment system
+### Disqus
 
+First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate
+Material for MkDocs with [Disqus][1], create an account and a site giving you a
+[shortname][3], and add it to `mkdocs.yml`:
 
+``` yaml
+extra:
+  disqus: <shortname>
+```
+
+This will insert a comment system on _every page, except the index page_.
+
+  [2]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
 
 ## Customization
 
 ### Selective integration
+
+If the [Metadata][4] extension is enabled, you can disable or enable Disqus for
+specific pages by adding the following to the front matter of a page:
+
+=== "Enable Disqus"
+
+    ``` markdown
+    ---
+    disqus: <shortname>
+    ---
+    ```
+
+=== "Disable Disqus"
+
+    ``` markdown
+    ---
+    disqus: ""
+    ---
+    ```
+
+  [4]: ../reference/meta-tags.md#metadata

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

@@ -31,7 +31,7 @@ google_analytics:
   [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
   [4]: https://support.google.com/analytics/answer/1042508
 
-### Tracking site search
+#### Enabling site search tracking
 
 Besides basic page views, _site search_ can also be tracked to better understand
 how people use your documentation and what they expect to find. To enable

docs/upgrading.md

@@ -2,29 +2,43 @@
 template: overrides/main.html
 ---
 
-# Upgrading to 5.x
+# Upgrading
 
-## Highlights
+Upgrade to the latest version with:
+
+``` sh
+pip install --upgrade mkdocs-material
+```
+
+Inspect the currently installed version with:
+
+``` sh
+pip show mkdocs-material
+```
+
+## Upgrading from 4.x to 5.x
+
+### What's new?
 
 * Reactive architecture – try `app.dialog$.next("Hi!")` in the console
-* [Instant loading][5] – make Material behave like a Single Page Application
+* [Instant loading][1] – make Material behave like a Single Page Application
-* Improved CSS customization with [CSS variables][1] – set your brand's colors
+* Improved CSS customization with [CSS variables][2] – set your brand's colors
 * Improved CSS resilience, e.g. proper sidebar locking for customized headers
-* Improved [icon integration][6] and configuration – now including over 5k icons
+* Improved [icon integration][3] and configuration – now including over 5k icons
 * Added possibility to use any icon for logo, repository and social links
 * Search UI does not freeze anymore (moved to web worker)
 * Search index built only once when using instant loading
 * Improved extensible keyboard handling
-* Support for [prebuilt search indexes][2]
+* Support for [prebuilt search indexes][4]
 * Support for displaying stars and forks for GitLab repositories
 * Support for scroll snapping of sidebars and search results
 * Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
 * Slight facelifting of some UI elements (Admonitions, tables, ...)
 
-  [1]: https://github.com/squidfunk/mkdocs-material/blob/081d540127c41703da3d73aa69eb521615c1cb89/src/assets/stylesheets/base/_colors.scss#L27-L55
+  [1]: setup/navigation.md#instant-loading
-  [2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [2]: setup/changing-the-colors.md#custom-colors
-
+  [3]: setup/changing-the-logo-and-icons.md#icons
-## How to upgrade
+  [4]: setup/setting-up-site-search.md#built-in-search
 
 ### Changes to `mkdocs.yml`
 
@@ -34,7 +48,7 @@ does not contain the key, you can skip it.
 
 #### `theme.feature`
 
-Optional features like [tabs][4] and [instant loading][5] are now implemented as
+Optional features like [tabs][5] and [instant loading][1] are now implemented as
 flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
 
 === "5.x"
@@ -54,13 +68,12 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
         tabs: true
     ```
 
-  [4]: ../../getting-started/#tabs
+  [5]: setup/navigation.md#navigation-tabs
-  [5]: ../../getting-started/#instant-loading
 
 #### `theme.logo.icon`
 
 The logo icon configuration was centralized under `theme.icon.logo` and can now
-be set to any of the [icons bundled with the theme][6]:
+be set to any of the [icons bundled with the theme][3]:
 
 === "5.x"
 
@@ -70,8 +83,6 @@ be set to any of the [icons bundled with the theme][6]:
         logo: material/cloud
     ```
 
-  [6]: ../../getting-started/#icons
-
 === "4.x"
 
     ``` yaml
@@ -83,7 +94,7 @@ be set to any of the [icons bundled with the theme][6]:
 #### `extra.repo_icon`
 
 The repo icon configuration was centralized under `theme.icon.repo` and can now
-be set to any of the [icons bundled with the theme][6]:
+be set to any of the [icons bundled with the theme][3]:
 
 === "5.x"
 
@@ -102,7 +113,7 @@ be set to any of the [icons bundled with the theme][6]:
 
 #### `extra.search.*`
 
-Search is now configured as part of the [plugin options][7]. Note that the
+Search is now configured as part of the [plugin options][6]. Note that the
 search languages must now be listed as an array of strings and the `tokenizer`
 was renamed to `separator`:
 
@@ -127,7 +138,7 @@ was renamed to `separator`:
         tokenizer: [\s\-\.]+
     ```
 
-  [7]: ../../plugins/search/#configuration
+  [6]: setup/setting-up-site-search.md#built-in-search
 
 #### `extra.social.*`
 
@@ -158,8 +169,8 @@ The templates have undergone a set of changes to make them future-proof. If
 you've used theme extension to override a block or template, make sure that it 
 matches the new structure:
 
-- If you've overridden a __block__, check `base.html` for potential changes
+- If you've overridden a **block**, check `base.html` for potential changes
-- If you've overridden a __template__, check the respective `*.html` file for
+- If you've overridden a **template**, check the respective `*.html` file for
   potential changes
 
 #### `base.html`
@@ -869,3 +880,26 @@ matches the new structure:
    {% endif %}
  </nav>
 ```
+
+## Upgrading from 3.x to 4.x
+
+### What's new?
+
+Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
+includes a mandatory change of the base font-size from `10px` to `20px` which
+means all `rem` values needed to be updated. Within the theme, `px` to `rem` 
+calculation is now encapsulated in a new function called `px2rem` which is part
+of the SASS code base.
+
+If you use Material for MkDocs with custom CSS that is based on `rem` values,
+note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
+`10px`, but `20px`. To learn more about the problem and implications, please
+refer to #911 in which the problem was discovered and fixed.
+
+### Changes to `mkdocs.yml`
+
+None.
+
+### Changes to `*.html` files
+
+None.

mkdocs.yml

@@ -131,6 +131,7 @@ nav:
     - Customization: customization.md
     #- Troubleshooting: troubleshooting.md
     - Data privacy: data-privacy.md
+    - License: license.md
   - Setup:
     - Changing the colors: setup/changing-the-colors.md
     - Changing the fonts: setup/changing-the-fonts.md
@@ -139,10 +140,10 @@ nav:
     - Setting up navigation: setup/setting-up-navigation.md
     - Setting up site search: setup/setting-up-site-search.md
     - Setting up site analytics: setup/setting-up-site-analytics.md
-    - Adding a git repository: setup/adding-a-git-repository.md
     - Adding social links: setup/adding-social-links.md
+    - Adding a git repository: setup/adding-a-git-repository.md
     - Adding a comment system: setup/adding-a-comment-system.md
-    - Adding an announcement bar: setup/adding-an-announcement-bar.md
+    #- Adding an announcement bar: setup/adding-an-announcement-bar.md
     #- Adding a landing page: setup/adding-a-landing-page.md
   - Reference:
     - Admonitions: reference/admonitions.md
@@ -150,16 +151,10 @@ nav:
     - Content tabs: reference/content-tabs.md
     - Footnotes: reference/footnotes.md
     - Lists: reference/lists.md
-  # - Releases:
+    - Meta tags: reference/meta-tags.md
-  #   - Upgrading to 5.x: releases/5.md
+  - Changelog:
-  #   - Upgrading to 4.x: releases/4.md
+    - Release notes: changelog.md
-  #   - Changelog: releases/changelog.md
+    - Upgrading: upgrading.md
-  # Changelog:
-  #  - Releases
-  #  - Migration
-
-  # - Contributing: contributing.md
-  # - License: license.md
 
 # Google Analytics
 google_analytics: