From b70342d9186b07bec4d494ca68042af039470b1d Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 3 Oct 2021 20:28:52 +0200 Subject: [PATCH] Updated parts of setup documentation --- docs/insiders/index.md | 2 +- docs/reference/diagrams.md | 74 +++++++++++-------------- docs/setup/setting-up-site-analytics.md | 11 +++- docs/setup/setting-up-site-search.md | 25 +++++---- docs/setup/setting-up-social-cards.md | 7 ++- docs/setup/setting-up-tags.md | 13 ++--- docs/setup/setting-up-the-footer.md | 24 +++++--- docs/setup/setting-up-the-header.md | 11 +++- docs/setup/setting-up-versioning.md | 10 ++-- 9 files changed, 94 insertions(+), 83 deletions(-) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index a2c8af534..01d310ebf 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -240,7 +240,7 @@ the public for general availability. [21]: ../setup/setting-up-navigation.md#sticky-navigation-tabs [22]: ../setup/setting-up-navigation.md#section-index-pages - [23]: ../setup/setting-up-the-footer.md#remove-generator + [23]: ../setup/setting-up-the-footer.md#generator-notice #### $ 2,500 – Biquinho Vermelho diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md index f8efcb636..140a33f67 100644 --- a/docs/reference/diagrams.md +++ b/docs/reference/diagrams.md @@ -6,22 +6,20 @@ template: overrides/main.html Diagrams help to communicate complex relationships and interconnections between different technical components, and are a great addition to project -documentation. Material for MkDocs integrates with [Mermaid.js][1], a very +documentation. Material for MkDocs integrates with [Mermaid.js], a very popular and flexible solution for drawing diagrams. - [1]: https://mermaid-js.github.io/mermaid/ + [Mermaid.js]: https://mermaid-js.github.io/mermaid/ ## Configuration -### SuperFences - -[:octicons-file-code-24: Source][2] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · :octicons-beaker-24: Experimental · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][2]{ .mdx-insiders } +[:octicons-tag-24: insiders-1.15.0 ... present][Insiders] -The [SuperFences][3] extension, which is part of [Python Markdown -Extensions][4], allows for adding __custom fences__, which can be used to -render [Mermaid.js][1] diagrams with zero effort: +This configuration enables native support for [Mermaid.js] diagrams. Material +for MkDocs will automatically initialize the JavaScript runtime when a page +includes a `mermaid` code block: ``` yaml markdown_extensions: @@ -32,51 +30,45 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format ``` -No further configuration is necessary. Material for MkDocs will automatically -load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced -`mermaid` block][5]. Furthermore: +No further configuration is necessary. Advantages over custom integration: -- [x] Works with [instant loading][6] without any additional effort +- [x] Works with [instant loading] without any additional effort - [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1] -- [x] Fonts and colors can be customized with [additional stylesheets][7] +- [x] Fonts and colors can be customized with [additional stylesheets] - [x] Support for both, light and dark color schemes -_While it's also possible to integrate [Mermaid.js][1] using existing +_While it's also possible to integrate [Mermaid.js] using existing third-party plugins[^2], the new native integration is recommended as it ensures interoperability with all Material for MkDocs features._ [^1]: - While all [Mermaid.js][1] features should work out-of-the-box, Material for + While all [Mermaid.js] features should work out-of-the-box, Material for MkDocs will currently adjust the fonts and colors for flow charts, sequence diagrams, class diagams, state diagrams and entity relationship diagrams. [^2]: - If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8] + If you don't want to use the native integration, [mkdocs-mermaid2-plugin] might be a good alternative. However, note that this plugin cannot be used - in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to + in conjunction with the [mkdocs-minify-plugin] and doesn't adapt to dark mode. - [2]: ../insiders/index.md - [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ - [4]: https://facelessuser.github.io/pymdown-extensions/ - [5]: #usage - [6]: ../setup/setting-up-navigation.md#instant-loading - [7]: ../customization.md#additional-css - [8]: https://github.com/fralau/mkdocs-mermaid2-plugin - [9]: https://github.com/byrnereese/mkdocs-minify-plugin + [Insiders]: ../insiders/index.md + [instant loading]: ../setup/setting-up-navigation.md#instant-loading + [additional stylesheets]: ../customization.md#additional-css + [mkdocs-mermaid2-plugin]: https://github.com/fralau/mkdocs-mermaid2-plugin + [mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin ## Usage -Mermaid diagrams are written as [code blocks][10] with the help of the -[SuperFences][11] extension. They must be enclosed with two separate lines -containing three backticks. +Mermaid diagrams are written as code blocks with the help of the [SuperFences]extension. They must be enclosed with two separate lines containing three +backticks. - [10]: code-blocks.md - [11]: #superfences + [code blocks]: code-blocks.md + [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences ### Using flowcharts -[Flowcharts][12] are diagrams that represent workflows or processes. The steps +[Flowcharts] are diagrams that represent workflows or processes. The steps are rendered as nodes of various kinds and are connected by edges, describing the necessary order of steps. @@ -104,11 +96,11 @@ graph LR B ---->|No| E[Yay!]; ``` - [12]: https://mermaid-js.github.io/mermaid/#/flowchart + [Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart ### Using sequence diagrams -[Sequence diagrams][13] describe a specific scenario as sequential interactions +[Sequence diagrams] describe a specific scenario as sequential interactions between multiple objects or actors, including the messages that are exchanged between those actors. @@ -142,11 +134,11 @@ sequenceDiagram Bob-->>John: Jolly good! ``` - [13]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram + [Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram ### Using state diagrams -[State diagrams][14] are a great tool to describe the behavior of a system, +[State diagrams] are a great tool to describe the behavior of a system, decomposing it into a finite number of states, and transitions between those states. @@ -194,11 +186,11 @@ stateDiagram-v2 } ``` - [14]: https://mermaid-js.github.io/mermaid/#/stateDiagram + [State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram ### Using class diagrams -[Class diagrams][15] are central to object oriented programing, describing the +[Class diagrams] are central to object oriented programing, describing the structure of a system by modelling entities as classes and relationships between them. @@ -266,11 +258,11 @@ classDiagram } ``` - [15]: https://mermaid-js.github.io/mermaid/#/classDiagram + [Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram ### Using entity-relationship diagrams -An [entity-relationship diagram][16] is composed of entity types and specifies +An [entity-relationship diagram] is composed of entity types and specifies relationships that exist between entities. It describes inter-related things in a specific domain of knowledge. @@ -294,4 +286,4 @@ erDiagram CUSTOMER }|..|{ DELIVERY-ADDRESS : uses ``` - [16]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram + [entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 894c7b9d4..8d895d801 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -16,7 +16,9 @@ and extendable [cookie consent][2]. ### Google Analytics -[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_ +:octicons-hash-24: Setting · +:octicons-milestone-24: Default: _none_ · +[:octicons-tag-24: 7.1.8 ... present][Google Analytics support] Material for MkDocs integrates with both, Google Analytics 4 and the now phasing out Universal Analytics (`UA-*`). Depending on the prefix of the property, add @@ -40,6 +42,7 @@ the following to `mkdocs.yml`: property: UA-XXXXXXXX-X ``` + [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8 [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html #### Site search tracking @@ -62,9 +65,10 @@ yourself, [this tutorial][4] might be a good start._ ### Cookie consent -[:octicons-file-code-24: Source][5] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +:octicons-hash-24: Setting · :octicons-milestone-24: Default: _none_ · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders } +[:octicons-tag-24: insiders-2.10.0 ... present][Insiders] Material for MkDocs ships a native and extensible cookie consent form, which asks the user for his consent prior to setting up analytics. Add the following @@ -125,6 +129,7 @@ e.g. privacy policy: [Change cookie settings](#__consent){ .md-button } ``` + [Insiders]: ../insiders/index.md [5]: ../insiders/index.md [6]: #custom-cookies [7]: ../assets/screenshots/consent.png diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index d77761ab9..a5c8b3dc1 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -146,9 +146,9 @@ Use them at your own risk._ ### Search suggestions -[:octicons-file-code-24: Source][8] · :octicons-unlock-24: Feature flag · -:octicons-beaker-24: Experimental +:octicons-beaker-24: Experimental · +[:octicons-tag-24: 7.2.0 ... present][Search suggestions support] When _search suggestions_ are enabled, the search will display the likeliest completion for the last word, saving the user many key strokes by accepting the @@ -166,15 +166,16 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^ [![Search suggestions][10]][10] + [Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0 [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/suggest/index.ts [9]: ?q=search+su [10]: ../assets/screenshots/search-suggestions.png ### Search highlighting -[:octicons-file-code-24: Source][11] · :octicons-unlock-24: Feature flag · -:octicons-beaker-24: Experimental +:octicons-beaker-24: Experimental · +[:octicons-tag-24: 7.2.0 ... present][Search highlighting support] When _search highlighting_ is enabled and a user clicks on a search result, Material for MkDocs will highlight all occurrences after following the link. @@ -190,15 +191,16 @@ Searching for [:octicons-search-24: code blocks][12] yields: [![Search highlighting][13]][13] + [Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0 [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/highlight/index.ts [12]: ../reference/code-blocks.md?h=code+blocks [13]: ../assets/screenshots/search-highlighting.png ### Search sharing -[:octicons-file-code-24: Source][14] · :octicons-unlock-24: Feature flag · -:octicons-beaker-24: Experimental +:octicons-beaker-24: Experimental · +[:octicons-tag-24: 7.2.0 ... present][Search highlighting support] When _search sharing_ is activated, a :material-share-variant: share button is rendered next to the reset button, which allows to deep link to the current @@ -215,6 +217,7 @@ clipboard. [![Search sharing][15]][15] + [Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0 [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/share/index.ts [15]: ../assets/screenshots/search-share.png @@ -245,9 +248,9 @@ For setup instructions, refer to the [official documentation][19]. ### Search boosting -[:octicons-file-code-24: Source][20] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · :octicons-note-24: Metadata · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders } +[:octicons-tag-24: insiders-2.8.0 ... present][Insiders] In order to give specific pages a higher relevance in search, [lunr][4] supports page-specific boosts, which can be defined for each page by leveraging the @@ -263,14 +266,16 @@ search: ... ``` + [Insiders]: ../insiders/index.md [20]: ../insiders/index.md [21]: ../reference/meta-tags.md#metadata ### Search exclusion -[:octicons-file-code-24: Source][20] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +:octicons-note-24: Metadata · :octicons-beaker-24: Experimental · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][20]{ .mdx-insiders } +[:octicons-tag-24: insiders-3.1.0 ... present][Insiders] #### Excluding pages diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index 07fdf9d6a..b86fa5085 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -23,10 +23,10 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1], ### Built-in social cards -[:octicons-file-code-24: Source][4] · -[:octicons-cpu-24: Plugin][4] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +:octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][4]{ .mdx-insiders } +[:octicons-tag-24: insiders-2.12.0 ... present][Insiders] The [built-in social cards plugin][4] generates a social card image for every page and adds the necessary meta tags, so it's displayed on social media when @@ -85,6 +85,7 @@ are available: cards_directory: assets/images/social ``` + [Insiders]: ../insiders/index.md [4]: ../insiders/index.md [5]: setting-up-site-analytics.md [6]: ../assets/screenshots/social-cards.png diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 4ccd32bc1..973a9a20e 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -13,10 +13,10 @@ can help to discover relevant information faster. ### Built-in tags -[:octicons-file-code-24: Source][1] · -[:octicons-cpu-24: Plugin][1] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +:octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][1]{ .mdx-insiders } +[:octicons-tag-24: insiders-2.7.0 ... present][Insiders] The [built-in tags plugin][1] adds the ability to categorize any page with tags as part of the front matter of the page. In order to add support for tags, add @@ -58,6 +58,7 @@ The following options are available: additional effort. The built-in tags plugin supports all of these features out-of-the-box. + [Insiders]: ../insiders/index.md [1]: ../insiders/index.md [2]: https://github.com/jldiaz/mkdocs-plugin-tags [3]: #adding-a-tags-index @@ -66,9 +67,6 @@ The following options are available: ### Adding tags -[:octicons-file-code-24: Source][1] · -:octicons-note-24: Metadata - If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled, tags can be added for any page as part of the front matter, e.g. to add the tags `insiders` and `brand new` to this page, add: @@ -125,9 +123,6 @@ arbitrary content before and after the marker: ### Hiding the tags -[:octicons-file-code-24: Source][1] · -:octicons-note-24: Metadata - While the tags are rendered above the main headline, sometimes, it might be desirable to hide them for a specific page, which can be achieved by using the [Metadata][10] extension: diff --git a/docs/setup/setting-up-the-footer.md b/docs/setup/setting-up-the-footer.md index 9f51c6735..a36b85f02 100644 --- a/docs/setup/setting-up-the-footer.md +++ b/docs/setup/setting-up-the-footer.md @@ -15,10 +15,11 @@ configured via `mkdocs.yml`. ### Social links -[:octicons-file-code-24: Source][1] · -:octicons-milestone-24: Default: _none_ +:octicons-hash-24: Setting · +:octicons-milestone-24: Default: _none_ · +[:octicons-tag-24: 1.0.0 ... present][Social links support] -All _social links_ are rendered next to the copyright information as part of the +Social links are rendered next to the copyright notice as part of the footer of your project documentation. Add a list of social links in `mkdocs.yml` with: @@ -48,6 +49,7 @@ For each entry, the following fields are available: * :fontawesome-brands-slack: – `fontawesome/brands/slack` * :fontawesome-brands-twitter: – `fontawesome/brands/twitter` + [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons @@ -91,21 +93,25 @@ For each entry, the following fields are available: ### Copyright notice -[:octicons-file-code-24: Source][3] · -:octicons-milestone-24: Default: _none_ +:octicons-hash-24: Setting · +:octicons-milestone-24: Default: _none_ · +[:octicons-tag-24: 0.1.0 ... present][Copyright notice support] -A custom _copyright banner_ can be rendered as part of the footer, which is +A custom copyright banner can be rendered as part of the footer, which is displayed next to the social links. It can be defined as part of `mkdocs.yml`: ``` yaml copyright: Copyright © 2016 - 2020 Martin Donath ``` + [Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/footer.html -### Remove generator +### Generator notice -[:octicons-file-code-24: Source][3] +:octicons-hash-24: Setting · +:octicons-milestone-24: Default: `true` · +[:octicons-tag-24: 7.3.0 ... present][Generator notice support] The footer displays a _Made with Material for MkDocs_ notice to denote how the site was generated. The notice can be removed with the following setting @@ -128,7 +134,7 @@ extra: consider [sponsoring][4] the project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders } - [4]: ../insiders/index.md + [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 ## Customization diff --git a/docs/setup/setting-up-the-header.md b/docs/setup/setting-up-the-header.md index efbb5c96d..c5644fd5d 100644 --- a/docs/setup/setting-up-the-header.md +++ b/docs/setup/setting-up-the-header.md @@ -16,8 +16,8 @@ It also includes the [search bar][1] and a place to display your project's ### Automatic hiding -[:octicons-file-code-24: Source][3] · -:octicons-unlock-24: Feature flag +:octicons-unlock-24: Feature flag · +[:octicons-tag-24: 6.2.0 ... present][Automatic hiding support] When _autohiding_ is enabled, the header is automatically hidden when the user scrolls past a certain threshold, leaving more space for content. Add the @@ -29,12 +29,15 @@ theme: - header.autohide ``` - [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_header.scss + [Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 ## Customization ### Announcement bar +:octicons-file-symlink-file-24: Customization · +[:octicons-tag-24: 5.0.0 ... present][Announcement bar support] + Material for MkDocs includes an announcement bar, which is the perfect place to display project news or other important information to the user. When the user scrolls past the header, the bar will automatically disappear. In order to add @@ -49,5 +52,7 @@ block][5], which is empty by default: {% endblock %} ``` + [Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 + [4]: ../customization.md#extending-the-theme [5]: ../customization.md#overriding-blocks-recommended diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md index 4eced590b..9257cc737 100644 --- a/docs/setup/setting-up-versioning.md +++ b/docs/setup/setting-up-versioning.md @@ -68,8 +68,9 @@ Material for MkDocs._ ### Version warning -[:octicons-file-code-24: Source][7] · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders } +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +:octicons-file-symlink-file-24: Customization · +[:octicons-tag-24: insiders-2.5.0 ... present][Insiders] If you're using versioning, you might want to display a warning when the user visits any other version than the latest version. Using [theme extension][8], @@ -108,6 +109,7 @@ extra: Make sure that this matches the [default version][11]. + [Insiders]: ../insiders/index.md [7]: ../insiders/index.md [8]: ../customization.md#extending-the-theme [9]: ../customization.md#overriding-blocks-recommended @@ -116,8 +118,8 @@ Make sure that this matches the [default version][11]. ### Stay on page -[:octicons-file-code-24: Source][7] · -[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders } +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.6.0 ... present][Insiders] Insiders improves the user experience when switching between versions: if version A and B contain a page with the same path name, the user will stay on