Fixed documentation

docs/creating-your-site.md

@@ -12,7 +12,7 @@ your project to be located and enter:
 mkdocs new .
 ```
 
-If you're running Material for MkDocs from within Docker, use:
+Alternatively, if you're running Material for MkDocs from within Docker, use:
 
 === "Unix"
 

docs/getting-started.md

@@ -35,23 +35,24 @@ Material for MkDocs can be installed with `pip`:
     ```
 
 This will automatically install compatible versions of all dependencies:
-[MkDocs][1], [Markdown][5], [Pygments][6] and [PyMdown Extensions][7]. Material
+[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
-for MkDocs always strives to support the latest versions, so there's no need to
+Material for MkDocs always strives to support the latest versions, so there's
-install those packages separately.
+no need to install those packages separately.
 
-Note that in order to install the [sponsor edition][8], you'll need to create a 
+Note that in order to install the [sponsor edition][8], you'll need to [become
-[personal access token][9] and set the `GH_TOKEN` environment variable to the
+a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN`
-token's value.
+environment variable to the token's value.
 
   [5]: https://python-markdown.github.io/
   [6]: https://pygments.org/
   [7]: https://facelessuser.github.io/pymdown-extensions/
   [8]: sponsorship.md
-  [9]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+  [9]: sponsorship.md#how-to-become-a-sponsor
+  [10]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
 
 ### with docker
 
-The official [Docker image][8] is a great way to get up and running in a few
+The official [Docker image][11] is a great way to get up and running in a few
 minutes, as it comes with all dependencies pre-installed. Pull the image for the 
 `latest` version with:
 
@@ -63,11 +64,11 @@ The `mkdocs` executable is provided as an entry point and `serve` is the
 default command. If you're not familar with Docker don't worry, we have you
 covered in the following sections.
 
-  [10]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+  [11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
 
 ### with git
 
-Material for MkDocs can be directly used from [GitHub][9] by cloning the
+Material for MkDocs can be directly used from [GitHub][12] by cloning the
 repository into a subfolder of your project root which might be useful if you
 want to use the very latest version:
 
@@ -90,4 +91,4 @@ cloning from `git`, you must install all required dependencies yourself:
 pip install -r mkdocs-material/requirements.txt
 ```
 
-  [11]: https://github.com/squidfunk/mkdocs-material
+  [12]: https://github.com/squidfunk/mkdocs-material

docs/publishing-your-site.md

@@ -5,7 +5,7 @@ template: overrides/main.html
 # Publishing your site
 
 The great thing about hosting project documentation in a `git` repository is
-the ability to automatically deploy it when new changes are pushed. MkDocs
+the ability to deploy it automatically when new changes are pushed. MkDocs
 makes this ridiculously simple.
 
 ## GitHub Pages

docs/reference/footnotes.md

@@ -15,7 +15,7 @@ footnotes and render them at the bottom of the page.
 
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 
-The [Footnotes][1] extension, which is part of the standard Markdown library,
+The [Footnotes][2] extension, which is part of the standard Markdown library,
 adds the ability to add inline footnotes to a document and can be enabled from
 `mkdocs.yml`:
 

docs/reference/meta-tags.md

@@ -4,7 +4,7 @@ template: overrides/main.html
 
 # Meta tags
 
-TBD
+<!-- TBD -->
 
 ## Configuration
 
@@ -24,6 +24,97 @@ markdown_extensions:
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
   [2]: https://python-markdown.github.io/extensions/meta_data/
 
-## Customization
+## Usage
 
-- add custom meta tags, like twitter cards etc via customization!?
+Metadata is written as a series of key-value pairs at the beginning of the
+Markdown document, delimited by a blank line which ends the metadata context.
+Naturally, the metadata is stripped from the document before rendering the
+actual page content and made available to the theme.
+
+Example:
+
+``` markdown
+---
+title: Lorem ipsum dolor sit amet
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+path: path/to/file
+source: file.js
+---
+
+# Headline
+
+...
+```
+
+See the next section which covers the supported metadata.
+
+### Setting a hero
+
+Material for MkDocs exposes a simple text-only page-local hero via Metadata, as
+you can see on the current page when you scroll to the top. It's as simple as:
+
+``` markdown
+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`.
+
+### Overrides
+
+#### Page title
+
+The page title can be overridden on a per-document basis:
+
+``` markdown
+title: Lorem ipsum dolor sit amet
+```
+
+This will set the `title` tag inside the document `head` for the current page
+to the provided value. It will also override the default behavior of Material
+for MkDocs which appends the site title using a dash as a separator to the page
+title.
+
+#### Page description
+
+The page description can also be overridden on a per-document basis:
+
+``` yaml
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+```
+
+This will set the `meta` tag containing the site description inside the
+document `head` for the current page to the provided value.

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

@@ -68,7 +68,7 @@ and [override the `analytics` block][6]:
 [:octicons-file-code-24: Source][2] · 
 :octicons-mortar-board-24: Difficulty: _easy_
 
-If you're using [instant loading][7], you may use the `location$` observable
+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
 a page view event with:
 

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

@@ -5,7 +5,7 @@ template: overrides/main.html
 # Setting up site search
 
 Material for MkDocs provides a great, client-side search implementation,
-omitting the need for the integation of third-party services, which might
+omitting the need for the integration of third-party services, which might
 violate data privacy regulations. Furthermore, with some effort, search can
 be made available [offline][1].
 
@@ -140,7 +140,7 @@ will not work out-of-the-box due to the restrictions modern browsers impose for
 security reasons. This can be mitigated with the [localsearch plugin][9] in
 combination with @squidfunk's [iframe-worker][10] polyfill.
 
-For [setup instructions][11], refer to the official documentation.
+For setup instructions, refer to the [official documentation][11].
 
   [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
   [9]: https://github.com/wilhelmer/mkdocs-localsearch/

docs/sponsorship.md

@@ -32,8 +32,8 @@ with the sponsor edition__][5].
 
 ## How to become a sponsor
 
-You've decided to become a sponsor? You're just __three easy steps__ away from 
+You've decided to become a sponsor? Great! You're just __three easy steps__ away
-enjoying the latest features of Material for MkDocs. Complete the following
+from enjoying the latest features of Material for MkDocs. Complete the following
 steps and you're in:
 
 - Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive
@@ -59,7 +59,7 @@ you're free to do at any time.__
 ## Roadmap
 
 The following list of funding goals – named after varieties of chili peppers 
-[I'm growing on my balcony][11] – show which features are already part of the 
+[I'm growing on my balcony][11] – shows, which features are already part of the
 sponsor edition or yet to come.
 
   [11]: https://www.instagram.com/squidfunk/
@@ -109,6 +109,8 @@ the following guidelines:
 
 - If you cancel your subscription, you're removed as a collaborator and will not
   receive future updates of the sponsor edition. However, you may continue to
-  use the latest version that's available to you for as long as you like.
+  use the latest version that's available to you for __as long as you like__.
+  Just remember that __[GitHub deletes private forks][13]__.
 
   [12]: license.md
+  [13]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository