From 43cdb9147229ec035ca20e5bb18b9e4b0c87b475 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 10 Oct 2021 17:39:53 +0200 Subject: [PATCH] Updated documentation --- CHANGELOG | 2 +- docs/data-privacy.md | 2 +- docs/reference/admonitions.md | 14 +- docs/reference/code-blocks.md | 12 +- docs/reference/content-tabs.md | 12 +- docs/reference/diagrams.md | 4 +- docs/reference/icons-emojis.md | 9 +- docs/reference/meta-tags.md | 15 +- docs/setup/changing-the-colors.md | 175 ++++---- docs/setup/changing-the-fonts.md | 89 +++-- docs/setup/changing-the-language.md | 133 ++++--- docs/setup/changing-the-logo-and-icons.md | 84 ++-- docs/setup/extensions/index.md | 4 +- .../extensions/python-markdown-extensions.md | 70 ++-- docs/setup/extensions/python-markdown.md | 44 +-- docs/setup/setting-up-navigation.md | 372 +++++++----------- docs/setup/setting-up-site-analytics.md | 4 +- docs/setup/setting-up-site-search.md | 14 +- docs/setup/setting-up-social-cards.md | 6 +- docs/setup/setting-up-tags.md | 2 +- docs/setup/setting-up-the-footer.md | 8 +- docs/setup/setting-up-the-header.md | 4 +- docs/setup/setting-up-versioning.md | 4 +- 23 files changed, 502 insertions(+), 581 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index b8087a62c..fc384ac79 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -138,7 +138,7 @@ mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20) mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18) - * Improved Mermaid.js intergration, now stable + * Improved Mermaid.js integration, now stable * Added support for sequence diagrams * Added support for entity relationship diagrams * Added support for cookie consent configuration diff --git a/docs/data-privacy.md b/docs/data-privacy.md index b85f7887f..722aa458c 100644 --- a/docs/data-privacy.md +++ b/docs/data-privacy.md @@ -19,7 +19,7 @@ CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily disabled][3] via `mkdocs.yml`. [2]: setup/changing-the-fonts.md - [3]: setup/changing-the-fonts.md#disabling-font-loading + [3]: setup/changing-the-fonts.md#autoloading ### Google Analytics and Disqus diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 3114fccfa..0a6ac406b 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -35,10 +35,11 @@ See additional configuration options: ### Admonition icons [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · -[:octicons-tag-24: insiders-2.4.0 ... present][Insiders] +[:octicons-tag-24: insiders-2.4.0][Insiders] Each of the supported admonition types has a distinct icon, which can be changed -to any icon bundled with the theme. Add the following lines to `mkdocs.yml`: +to any icon bundled with the theme, or even a [custom icon]. Add the following +lines to `mkdocs.yml`: ``` yaml theme: @@ -106,6 +107,7 @@ theme: [![FontAwesome]][FontAwesome] [Insiders]: ../insiders/index.md + [custom icon]: icons-emojis.md#additional-icons [supported types]: #supported-types [icon search]: icons-emojis.md#search [Octicons]: ../assets/screenshots/admonition-octicons.png @@ -234,8 +236,8 @@ _Result_: ### Inline blocks -:octicons-beaker-24: Experimental · -[:octicons-tag-24: 7.0.0 ... present][Inline support] +[:octicons-tag-24: 7.0.0][Inline support] · +:octicons-beaker-24: Experimental Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing them to the right using the `inline` + `end` modifiers, or to the left using @@ -441,7 +443,7 @@ _Example_: purus auctor massa, nec semper lorem quam in massa. ``` -=== ":octicons-file-code-16: docs/stylesheets/admonitions.css" +=== ":octicons-file-code-16: docs/stylesheets/extra.css" ``` css :root { @@ -468,7 +470,7 @@ _Example_: ``` yaml extra_css: - - stylesheets/admonitions.css + - stylesheets/extra.css ``` _Result_: diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 2a40425d6..68be1298c 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -40,9 +40,9 @@ See additional configuration options: ### Code annotations [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.2.0][Insiders] · :octicons-unlock-24: Feature flag · -:octicons-beaker-24: Experimental · -[:octicons-tag-24: insiders-2.2.0 ... present][Insiders] +:octicons-beaker-24: Experimental Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block @@ -297,7 +297,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are several [types of string tokens], they use the same color. You can assign a new color by using an [additional style sheet]: -=== ":octicons-file-code-16: docs/stylesheets/colors.css" +=== ":octicons-file-code-16: docs/stylesheets/extra.css" ``` css :root > * { @@ -309,14 +309,14 @@ a new color by using an [additional style sheet]: ``` yaml extra_css: - - stylesheets/colors.css + - stylesheets/extra.css ``` If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you can lookup the specific CSS class name in the [syntax theme definition], and override it as part of your [additional style sheet]: -=== ":octicons-file-code-16: docs/stylesheets/colors.css" +=== ":octicons-file-code-16: docs/stylesheets/extra.css" ``` css .highlight .sb { @@ -328,7 +328,7 @@ override it as part of your [additional style sheet]: ``` yaml extra_css: - - stylesheets/colors.css + - stylesheets/extra.css ``` [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md index 273db0390..1cca9411c 100644 --- a/docs/reference/content-tabs.md +++ b/docs/reference/content-tabs.md @@ -33,9 +33,9 @@ See additional configuration options: ### Linked content tabs [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.9.0][Insiders] · :octicons-unlock-24: Feature flag · -:octicons-beaker-24: Experimental · -[:octicons-tag-24: insiders-2.9.0 ... present][Insiders] +:octicons-beaker-24: Experimental When enabled, all content tabs across the whole documentation site will be linked and switch to the same label when the user clicks on a tab. Add the @@ -54,16 +54,16 @@ integrated with [instant loading] and persisted across page loads. === ":octicons-check-circle-fill-16: Enabled" - [![linking enabled]][linking enabled] + [![content.tabs.link enabled]][content.tabs.link enabled] === ":octicons-skip-16: Disabled" - [![linking disabled]][linking disabled] + [![content.tabs.link disabled]][content.tabs.link disabled] [Insiders]: ../insiders/index.md [instant loading]: ../setup/setting-up-navigation.md#instant-loading - [linking enabled]: ../assets/screenshots/content-tabs-link.png - [linking disabled]: ../assets/screenshots/content-tabs.png + [content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png + [content.tabs.link disabled]: ../assets/screenshots/content-tabs.png ## Usage diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md index 3235d5389..f76370521 100644 --- a/docs/reference/diagrams.md +++ b/docs/reference/diagrams.md @@ -14,8 +14,8 @@ popular and flexible solution for drawing diagrams. ## Configuration [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · -:octicons-beaker-24: Experimental · -[:octicons-tag-24: insiders-1.15.0 ... present][Insiders] +[:octicons-tag-24: insiders-1.15.0][Insiders] · +:octicons-beaker-24: Experimental This configuration enables native support for [Mermaid.js] diagrams. Material for MkDocs will automatically initialize the JavaScript runtime when a page diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index 2a7ede75c..fff540013 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -57,7 +57,6 @@ See additional configuration options: [Material Design]: https://materialdesignicons.com/ [FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free [Octicons]: https://octicons.github.com/ - [additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons @@ -136,7 +135,7 @@ _Example_: - :fontawesome-brands-facebook:{ .facebook } – Facebook ``` -=== ":octicons-file-code-16: docs/stylesheets/icons.css" +=== ":octicons-file-code-16: docs/stylesheets/extra.css" ``` css .medium { @@ -154,7 +153,7 @@ _Example_: ``` yaml extra_css: - - stylesheets/icons.css + - stylesheets/extra.css ``` _Result_: @@ -181,7 +180,7 @@ _Example_: :octicons-heart-fill-24:{ .heart } ``` -=== ":octicons-file-code-16: docs/stylesheets/icons.css" +=== ":octicons-file-code-16: docs/stylesheets/extra.css" ``` css @keyframes heart { @@ -201,7 +200,7 @@ _Example_: ``` yaml extra_css: - - stylesheets/icons.css + - stylesheets/extra.css ``` _Result_: diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index fc166fc13..9186e0dd8 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -34,9 +34,8 @@ See additional configuration options: ### Setting the page title -When [Metadata] is enabled, the page title can be overridden on a per-document -basis with custom front matter. Add the following lines at the top of a Markdown -file: +When [Metadata] is enabled, the page title can be overridden for a document with +some custom front matter. Add the following lines at the top of a Markdown file: ``` bash --- @@ -57,9 +56,9 @@ title: Lorem ipsum dolor sit amet # (1) ### Setting the page description -When [Metadata] is enabled, the page description can also be overridden on a -per-document basis with custom front matter. Add the following lines at the top -of a Markdown file: +When [Metadata] is enabled, the page description can be overridden for a +document with custom front matter. Add the following lines at the top of a +Markdown file: ``` bash --- @@ -77,8 +76,8 @@ document `head` for the current page to the provided value. ### Adding a web app manifest +[:octicons-tag-24: 3.1.0][manifest support] · :octicons-archive-24: Deprecated · -[:octicons-tag-24: 3.1.0 ... present][web app manifest support] · :octicons-trash-24: 8.0.0 A [web app manifest] is a simple JSON file that specifies how your web @@ -94,7 +93,7 @@ extra: can be achieved with [theme extension]. [web app manifest]: https://developers.google.com/web/fundamentals/web-app-manifest/ - [web app manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0 + [manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0 [theme extension]: ../customization.md#extending-the-theme diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index f87c1fa14..632155833 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -5,12 +5,12 @@ template: overrides/main.html # Changing the colors As any proper Material Design implementation, Material for MkDocs supports -Google's original [color palette][1], which can be easily configured through +Google's original [color palette], which can be easily configured through `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to -fit your brand's identity by using [CSS variables][2]. +fit your brand's identity by using [CSS variables][custom colors]. - [1]: http://www.materialui.co/colors - [2]: #custom-colors + [color palette]: http://www.materialui.co/colors + [custom colors]: #custom-colors ## Configuration @@ -18,9 +18,10 @@ fit your brand's identity by using [CSS variables][2]. #### Color scheme -[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default` +[:octicons-tag-24: 5.2.0][palette.scheme support] · +:octicons-milestone-24: Default: `default` -Material for MkDocs supports two _color schemes_: a light mode, which is just +Material for MkDocs supports two color schemes: a light mode, which is just called `default`, and a dark mode, which is called `slate`. The color scheme can be set via `mkdocs.yml`: @@ -30,7 +31,7 @@ theme: scheme: default ``` -_Click on a tile to change the color scheme_: +Click on a tile to change the color scheme:
@@ -49,13 +50,14 @@ _Click on a tile to change the color scheme_: }) - [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss + [palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 #### Primary color -[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo` +[:octicons-tag-24: 0.2.0][palette.primary support] · +:octicons-milestone-24: Default: `indigo` -The _primary color_ is used for the header, the sidebar, text links and several +The primary color is used for the header, the sidebar, text links and several other components. In order to change the primary color, set the following value in `mkdocs.yml` to a valid color name: @@ -65,7 +67,7 @@ theme: primary: indigo ``` -_Click on a tile to change the primary color_: +Click on a tile to change the primary color:
@@ -103,13 +105,14 @@ _Click on a tile to change the primary color_: }) - [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss + [palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 #### Accent color -[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo` +[:octicons-tag-24: 0.2.0][palette.accent support] · +:octicons-milestone-24: Default: `indigo` -The _accent color_ is used to denote elements that can be interacted with, e.g. +The accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by choosing a valid color name: @@ -119,7 +122,7 @@ theme: accent: indigo ``` -_Click on a tile to change the accent color_: +Click on a tile to change the accent color: