Added notes on deprecations

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

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`.
 

mkdocs.yml

@@ -170,6 +170,7 @@ nav:
   - Changelog:
     - Release notes: changelog.md
     - Upgrading: upgrading.md
+    - Deprecations: deprecations.md
 
 # Google Analytics
 google_analytics: