From c0e5f9f1b9166fefb91dbe880402cd938bb45329 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 22 Jul 2020 19:11:22 +0200 Subject: [PATCH] Fixed documentation --- docs/creating-your-site.md | 2 +- docs/getting-started.md | 23 +++--- docs/publishing-your-site.md | 2 +- docs/reference/footnotes.md | 2 +- docs/reference/meta-tags.md | 97 ++++++++++++++++++++++++- docs/setup/setting-up-site-analytics.md | 2 +- docs/setup/setting-up-site-search.md | 4 +- docs/sponsorship.md | 10 ++- 8 files changed, 118 insertions(+), 24 deletions(-) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index fc9014029..6c5a5c09e 100644 --- a/docs/creating-your-site.md +++ b/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" diff --git a/docs/getting-started.md b/docs/getting-started.md index cf01b74f4..ba8fe2080 100644 --- a/docs/getting-started.md +++ b/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 -for MkDocs always strives to support the latest versions, so there's no need to -install those packages separately. +[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7]. +Material for MkDocs always strives to support the latest versions, so there's +no need to install those packages separately. -Note that in order to install the [sponsor edition][8], you'll need to create a -[personal access token][9] and set the `GH_TOKEN` environment variable to the -token's value. +Note that in order to install the [sponsor edition][8], you'll need to [become +a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN` +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 diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index 6786b10c3..87a111a03 100644 --- a/docs/publishing-your-site.md +++ b/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 diff --git a/docs/reference/footnotes.md b/docs/reference/footnotes.md index 4b93299dd..b4d4e312a 100644 --- a/docs/reference/footnotes.md +++ b/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`: diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index 7af2ef4ea..288a0fea8 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -4,7 +4,7 @@ template: overrides/main.html # Meta tags -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. diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 6285bf401..b941c9df0 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/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: diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 9f9d03134..6d0a387fc 100644 --- a/docs/setup/setting-up-site-search.md +++ b/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/ diff --git a/docs/sponsorship.md b/docs/sponsorship.md index 1458ca6a8..cfcd59c0a 100644 --- a/docs/sponsorship.md +++ b/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 -enjoying the latest features of Material for MkDocs. Complete the following +You've decided to become a sponsor? Great! You're just __three easy steps__ away +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