From f36bb0de83634e8b66356a0808c3fe03317188f2 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Thu, 23 Jul 2020 16:07:16 +0200
Subject: [PATCH] Added notes on deprecations

---
 docs/deprecations.md        | 72 +++++++++++++++++++++++++++++++++++++
 docs/reference/meta-tags.md | 42 ++--------------------
 mkdocs.yml                  |  1 +
 3 files changed, 76 insertions(+), 39 deletions(-)
 create mode 100644 docs/deprecations.md

diff --git a/docs/deprecations.md b/docs/deprecations.md
new file mode 100644
index 000000000..065631893
--- /dev/null
+++ b/docs/deprecations.md
@@ -0,0 +1,72 @@
+---
+template: overrides/main.html
+---
+
+# Deprecations
+
+This page includes a list of deprecations, indicating which features should not
+be used anymore, as they will be removed in a future release.
+
+## Front matter
+
+### Redirects
+
+:octicons-archive-24: Deprecated: 5.5.0 ·
+:octicons-trash-24: Will be removed in 6.0
+
+The `redirect` key, which could be added via [Metadata][1], allowed to
+specify a redirect URL from within a markdown page to a new address, to notify
+the user when content was moved:
+
+``` markdown
+---
+redirect: /path/to/new/file
+---
+```
+
+The [mkdocs-redirects][2] plugin provides the ability to define redirect
+mappings via `mkdocs.yml`, which is considered to be a much better solution to
+achieve the same result:
+
+``` yaml
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        path/to/old/file.md: path/to/new/file.md
+```
+
+  [1]: reference/meta-tags.md#metadata
+  [2]: https://github.com/datarobot/mkdocs-redirects
+
+### Linking sources
+
+:octicons-archive-24: Deprecated: 5.5.0 ·
+:octicons-trash-24: Will be removed in 6.0
+
+The `source` and `path` keys, which could be added via [Metadata][1], showed
+a source icon at the top right of a document, linking a document to a single
+source file:
+
+``` markdown
+---
+path: tree/master/docs
+source: deprecations.md
+---
+```
+
+Only a single source file could be linked, which is useless if a document refers
+to multiple files (or multiple sections within a single file). A more flexible
+approach is to use the new [icon integration][3]:
+
+``` markdown
+[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
+```
+
+This will render as:
+
+[:octicons-file-code-24: Source][4]
+
+
+  [3]: setup/changing-the-logo-and-icons.md#icons
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md
diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md
index dd26a059f..c64dd90bb 100644
--- a/docs/reference/meta-tags.md
+++ b/docs/reference/meta-tags.md
@@ -10,11 +10,9 @@ template: overrides/main.html
 
 ### Metadata
 
-[:octicons-workflow-24: Extension][1]
-
-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 via `mkdocs.yml`:
+The [Metadata][1] extension, which is part of the standard Markdown library,
+adds the ability to add front matter to a document and can be enabled via
+`mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -36,8 +34,6 @@ Example:
 ---
 title: Lorem ipsum dolor sit amet
 description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
-path: path/to/file
-source: file.js
 ---
 
 # Headline
@@ -56,39 +52,7 @@ you can see on the current page when you scroll to the top. It's as simple as:
 hero: Set heroes with metadata
 ```
 
-### Linking sources
 
-When a document is related to a specific source file and the `repo_url` is
-defined inside the project's `mkdocs.yml`, the file can be linked using the
-`source` key:
-
-``` markdown
-source: file.js
-```
-
-The filename is appended to the `repo_url` set in `mkdocs.yml`, but can be
-prefixed with a `path` to ensure correct path resolving. The name of the source
-file is shown in the tooltip.
-
-Example:
-
-``` markdown
-path: tree/master/docs/extensions
-source: metadata.md
-```
-
-### Redirecting to another page
-
-It's sometimes necessary to move documents around in the navigation tree and
-redirect users from the old URL to the new one. The `redirect` meta-tag allows
-to create a redirection from the current document to the address specified in
-the tag.
-
-For instance, if your document contains:
-
-``` markdown
-redirect: /new/url
-```
 
 accessing that document's URL will automatically redirect to `/new/url`.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 8c1f5fab0..3145c3071 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -170,6 +170,7 @@ nav:
   - Changelog:
     - Release notes: changelog.md
     - Upgrading: upgrading.md
+    - Deprecations: deprecations.md
 
 # Google Analytics
 google_analytics: