From f9d0f24a99ae09e78043917337da1b12d0a5ef7b Mon Sep 17 00:00:00 2001 From: squidfunk Date: Thu, 23 Jul 2020 17:00:20 +0200 Subject: [PATCH] Adjusted front matter and deprecation docs --- docs/deprecations.md | 65 ++++++++++++++++++++++------ docs/reference/code-blocks.md | 26 ++++++++--- docs/reference/lists.md | 4 +- docs/reference/meta-tags.md | 39 +++++------------ docs/setup/setting-up-site-search.md | 2 +- 5 files changed, 85 insertions(+), 51 deletions(-) diff --git a/docs/deprecations.md b/docs/deprecations.md index 065631893..beb689435 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -4,19 +4,20 @@ 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. +This page includes a list of deprecations, indicating which features of Material +for MkDocs were replaced with newer, more flexible alternatives, and thus should +not be used anymore. ## Front matter -### Redirects +### Redirect :octicons-archive-24: Deprecated: 5.5.0 · -:octicons-trash-24: Will be removed in 6.0 +:octicons-trash-24: Removal: 6.x 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: +specify a redirect from within a document to a new address, which is a good +idea when moving content around: ``` markdown --- @@ -39,14 +40,14 @@ plugins: [1]: reference/meta-tags.md#metadata [2]: https://github.com/datarobot/mkdocs-redirects -### Linking sources +### Source link :octicons-archive-24: Deprecated: 5.5.0 · -:octicons-trash-24: Will be removed in 6.0 +:octicons-trash-24: Removal: 6.x 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: +a source icon at the top right corner of a document, linking a document to a +single source file: ``` markdown --- @@ -63,10 +64,46 @@ approach is to use the new [icon integration][3]: [: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] - +This will render as [:octicons-file-code-24: Source][4], which can be included +at arbitrary positions in any document. [3]: setup/changing-the-logo-and-icons.md#icons [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md + +### Hero + +:octicons-archive-24: Deprecated: 5.5.0 · +:octicons-trash-24: Removal: 6.x + +The `hero` key, which could be added via [Metadata][1], allowed to render a +simple, text-only and page-local teaser text as part of a document. It could +be set from front matter with: + +``` markdown +--- +hero: Lorem ipsum dolor sit amet +--- +``` + +The recommended way is to [override the `hero` block][5] via [theme +extension][6] for a specific page, which has the nice side effect that hero +templates can be shared among multiple pages: + +=== "Markdown" + + ``` markdown + --- + template: overrides/hero.html + --- + ``` + +=== "Template" + + ``` jinja + {% block hero %} + {# Add custom hero here #} + {% endblock %} + ``` + + [5]: customization.md#overriding-blocks + [6]: customization.md#extending-the-theme diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 15d59d4dd..05c8afc15 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -22,7 +22,7 @@ The [Highlight][3] extension, which is part of [Python Markdown Extensions][5], integrates with Material for MkDocs and provides several options for configuring syntax highlighting of code blocks: -`use_pygments`{: #use_pygments } +`use_pygments`{: #use-pygments } : :octicons-milestone-24: Default: `true` – This option allows to control whether highlighting should be carried out during build time by @@ -84,7 +84,7 @@ configuring syntax highlighting of code blocks: linenums: true ``` -`linenums_style`{: #linenums_style } +`linenums_style`{: #linenums-style } : :octicons-milestone-24: Default: `table` – The Highlight extension provides three ways to add line numbers, all of which are supported by Material for @@ -283,7 +283,7 @@ The `#!python range()` function is used to generate a sequence of numbers. ### Adding keyboard keys -When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax. +When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax. Consult the [Python Markdown Extensions][16] documentation to learn about all available short key codes. @@ -299,9 +299,9 @@ _Result_: [19]: #keys -### Adding external files +### Embedding external files -When [Snippets][20] is enabled, content from other files can be inserted, which +When [Snippets][20] is enabled, content from other files can be embedded, which is especially useful to reference and embed the contents of source files directly into your project documentation. @@ -320,7 +320,21 @@ _Result_: ``` Note that [Snippets][20] is not limited to code blocks, but can be used anywhere -in a Markdown file to put repeating content into separate files, which is also +from a document to move repeating content to separate files, which is also explained in the [official documentation][16]. [20]: #snippets + +## Customization + +### Custom syntax theme + +[:octicons-file-code-24: Source][21] · +:octicons-mortar-board-24: Difficulty: _easy_ + +If syntax highlighting is done with [Pygments][22], Material for MkDocs +provides the styles defining the [appeareance][21] of code blocks, which can +be adjusted with [additional stylesheets][6]. + + [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/_codehilite.scss + [22]: #use-pygments diff --git a/docs/reference/lists.md b/docs/reference/lists.md index 166db6085..1379af72b 100644 --- a/docs/reference/lists.md +++ b/docs/reference/lists.md @@ -35,7 +35,7 @@ The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5], adds support for lists with styled checkboxes, and provides several options for configuring the style: -`custom_checkbox`{: #custom_checkbox } +`custom_checkbox`{: #custom-checkbox } : :octicons-milestone-24: Default: `false` · This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, @@ -47,7 +47,7 @@ configuring the style: custom_checkbox: true ``` -`clickable_checkbox`{: #clickable_checkbox } +`clickable_checkbox`{: #clickable-checkbox } : :octicons-milestone-24: Default: `false` · This option toggles whether checkboxes are clickable. As the state is not persisted, the use of this diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index c64dd90bb..ea7ca8f12 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -4,8 +4,6 @@ template: overrides/main.html # Meta tags - - ## Configuration ### Metadata @@ -23,12 +21,10 @@ markdown_extensions: ## Usage -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: +Front matter is written as a series of key-value pairs at the beginning of the +Markdown document, delimited by a blank line which ends the YAML context. +Naturally, front matter is stripped from the document before rendering the +actual page content and made available to the theme: ``` markdown --- @@ -41,29 +37,14 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. ... ``` -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 -``` - - - -accessing that document's URL will automatically redirect to `/new/url`. - -### Overrides - -#### Page title +### Setting the 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 @@ -71,12 +52,14 @@ 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 +### Setting the page description The page description can also be overridden on a per-document basis: -``` yaml +``` markdown +--- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. +--- ``` This will set the `meta` tag containing the site description inside the diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 6d0a387fc..5e26706ac 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -102,7 +102,7 @@ The following options are supported: separator: '[\s\-\.]+' ``` -`prebuild_index`{: #prebuild_index } +`prebuild_index`{: #prebuild-index } : :octicons-milestone-24: Default: `false` · :octicons-beaker-24: Experimental – MkDocs can generate a [prebuilt index][7] of all pages during