From a0ff73932f4c227281c1e148897a843449b52460 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 10 Oct 2021 19:22:13 +0200 Subject: [PATCH] Updated documentation --- docs/reference/admonitions.md | 24 +-- docs/reference/images.md | 8 +- docs/setup/changing-the-colors.md | 3 + docs/setup/changing-the-language.md | 24 ++- .../extensions/python-markdown-extensions.md | 18 +-- docs/setup/extensions/python-markdown.md | 6 +- docs/setup/setting-up-navigation.md | 4 +- docs/setup/setting-up-site-analytics.md | 149 +++++++++--------- docs/setup/setting-up-site-search.md | 10 +- docs/setup/setting-up-social-cards.md | 113 +++++++------ docs/setup/setting-up-tags.md | 57 +++---- docs/setup/setting-up-the-footer.md | 6 +- docs/setup/setting-up-versioning.md | 38 ++--- 13 files changed, 222 insertions(+), 238 deletions(-) diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 0a6ac406b..63ee250fd 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -299,7 +299,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. Following is a list of type qualifiers provided by Material for MkDocs, whereas the default type, and thus fallback for unknown type qualifiers, is `note`: -`note`{ #note }, ~~`seealso`~~ [^1] +`note`{ #type-note }, ~~`seealso`~~ [^1] : !!! note @@ -307,7 +307,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`abstract`{ #abstract }, `summary`, `tldr` +`abstract`{ #type-abstract }, `summary`, `tldr` : !!! abstract @@ -315,7 +315,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`info`{ #info }, `todo` +`info`{ #type-info }, `todo` : !!! info @@ -323,7 +323,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`tip`{ #tip }, `hint`, `important` +`tip`{ #type-tip }, `hint`, `important` : !!! tip @@ -331,7 +331,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`success`{ #success }, `check`, `done` +`success`{ #type-success }, `check`, `done` : !!! success @@ -339,7 +339,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`question`{ #question }, `help`, `faq` +`question`{ #type-question }, `help`, `faq` : !!! question @@ -347,7 +347,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`warning`{ #warning }, `caution`, `attention` +`warning`{ #type-warning }, `caution`, `attention` : !!! warning @@ -355,7 +355,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`failure`{ #failure }, `fail`, `missing` +`failure`{ #type-failure }, `fail`, `missing` : !!! failure @@ -363,7 +363,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`danger`{ #danger }, `error` +`danger`{ #type-danger }, `error` : !!! danger @@ -371,7 +371,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`bug`{ #bug } +`bug`{ #type-bug } : !!! bug @@ -379,7 +379,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`example`{ #example } +`example`{ #type-example } : !!! example @@ -387,7 +387,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`quote`{ #quote }, `cite` +`quote`{ #type-quote }, `cite` : !!! quote diff --git a/docs/reference/images.md b/docs/reference/images.md index f7856bbee..b890848de 100644 --- a/docs/reference/images.md +++ b/docs/reference/images.md @@ -120,16 +120,10 @@ _Result_: Modern browsers provide [native support for lazy-loading images][lazy-loading] through the `loading=lazy` directive, which degrades to eager-loading in -browsers without support - -_Example_: +browsers without support: ``` markdown ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ loading=lazy } ``` -_Result_: - -![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 } - [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 632155833..ab4bce489 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -312,6 +312,9 @@ in the [color schemes][palette.scheme] section: === ":octicons-file-code-16: mkdocs.yml" ``` yaml + theme: + palette: + scheme: youtube extra_css: - stylesheets/extra.css ``` diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md index bfe1867d7..4bb02fc36 100644 --- a/docs/setup/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -132,12 +132,12 @@ The following properties must be set for each alternate language: the `hreflang` attribute of the link, improving discoverability via search engines. -[![Language selector]][Language selector] +[![Language selector preview]][Language selector preview] [alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes - [Language selector]: ../assets/screenshots/language-selection.png + [Language selector preview]: ../assets/screenshots/language-selection.png ### Directionality @@ -180,23 +180,31 @@ Click on a tile to change the directionality: If you want to customize some of the translations for a language, just follow the guide on [theme extension] and create a new partial in the `overrides` -folder. Then import the [translations] of your language as a fallback and only +folder. Then, import the [translations] of the language as a fallback and only adjust the ones you want to override: === ":octicons-file-code-16: partials/languages/custom.html" ``` html - - {% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %} + + {% import "partials/languages/de.html" as language %} + {% import "partials/languages/en.html" as fallback %} + + {% macro override(key) %}{{ { - "toc.title": "On this page" + "toc.title": "Auf dieser Seite" }[key] }}{% endmacro %} - {% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %} + {% macro t(key) %}{{ + override(key) or language(key) or fallback.t(key) + }}{% endmacro %} ``` - 1. Check the [list of available languages], pick the translation you want + 1. Note that `en` must always be used as a fallback language, as it's the + default theme language. + + 2. Check the [list of available languages], pick the translation you want to override for your language and add them here. === ":octicons-file-code-16: mkdocs.yml" diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index a6d05ef9d..8400fc78c 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -154,7 +154,7 @@ markdown_extensions: The following configuration options are supported: -`mode`{ #mode } +`mode`{ #critic-mode } : :octicons-milestone-24: Default: `view` – This option defines how the markup should be parsed, i.e. whether to just `view` all suggested changes, or @@ -265,7 +265,7 @@ The following configuration options are supported: : :octicons-milestone-24: Default: _none_ – This option allows to list folders with additional icon sets to be used in Markdown or `mkdocs.yml`, which is - explained in more detail in the [icon customization guide]. + explained in more detail in the [icon customization guide]: ``` yaml markdown_extensions: @@ -318,7 +318,7 @@ markdown_extensions: The following configuration options are supported: -`use_pygments`{ #use-pygments } +`use_pygments`{ #highlight-use-pygments } : :octicons-milestone-24: Default: `true` – This option allows to control whether highlighting should be carried out during build time using @@ -365,7 +365,7 @@ The following configuration options are supported: Note that [Highlight.js] has no affiliation with the Highlight extension. -`linenums`{ #linenums } +`linenums`{ #highlight-linenums } : :octicons-milestone-24: Default: `false` – This option will add line numbers to _all_ code blocks. If you wish to add line numbers to _some_, but not all @@ -379,7 +379,7 @@ The following configuration options are supported: linenums: true ``` -`linenums_style`{ #linenums-style } +`linenums_style`{ #highlight-linenums-style } : :octicons-milestone-24: Default: `table` – The [Highlight] extension provides three ways to add line numbers, all of which are supported by @@ -544,7 +544,7 @@ markdown_extensions: The following configuration options are supported: -`custom_fences`{ #custom-fences } +`custom_fences`{ #superfences-custom-fences } : :octicons-milestone-24: Default: _none_ – This option allows to define a handler for custom fences, e.g. to preserve the definitions of [Mermaid.js] @@ -603,7 +603,7 @@ markdown_extensions: The following configuration options are supported: -`alternate_style`{ #alternate-style } +`alternate_style`{ #tabbed-alternate-style } : :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1] [Tabbed alternate support] – This option enables the [alternate style] of @@ -652,7 +652,7 @@ markdown_extensions: The following configuration options are supported: -`custom_checkbox`{ #custom-checkbox } +`custom_checkbox`{ #tasklist-custom-checkbox } : :octicons-milestone-24: Default: `false` · This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, @@ -664,7 +664,7 @@ The following configuration options are supported: custom_checkbox: true ``` -`clickable_checkbox`{ #clickable-checkbox } +`clickable_checkbox`{ #tasklist-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/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 2ef97fb28..89c43ed76 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -213,7 +213,7 @@ markdown_extensions: The following configuration options are supported: -`permalink`{ #permalink } +`permalink`{ #toc-permalink } : :octicons-milestone-24: Default: `false` – This option adds an anchor link containing the paragraph symbol `¶` or another custom symbol at the end of @@ -236,7 +236,7 @@ The following configuration options are supported: permalink: ⚓︎ ``` -`slugify`{ #slugify } +`slugify`{ #toc-slugify } : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for customization of the slug function. For some languages, the default may not @@ -259,7 +259,7 @@ The following configuration options are supported: slugify: !!python/name:pymdownx.slugs.uslugify_cased ``` -`toc_depth`{ #toc_depth } +`toc_depth`{ #toc-depth } : :octicons-milestone-24: Default: `6` – Define the range of levels to be included in the table of contents. This may be useful for project diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 14eb44cbd..4945242e8 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -317,7 +317,7 @@ hide: Material for MkDocs includes several keyboard shortcuts that make it possible to navigate your project documentation via keyboard. There're two modes: -`search`{ #search } +`search`{ #mode-search } : This mode is active when the _search is focused_. It provides several key bindings to make search accessible and navigable via keyboard: @@ -326,7 +326,7 @@ to navigate your project documentation via keyboard. There're two modes: * ++esc++ , ++tab++ : close search dialog * ++enter++ : follow selected result -`global`{ #global } +`global`{ #mode-global } : This mode is active when _search is not focussed_ and when there's no other focussed element that is susceptible to keyboard input. The following keys diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 15337adcb..d451face2 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -6,25 +6,24 @@ template: overrides/main.html As with any other service offered on the web, understanding how your project documentation is actually used can be an essential success factor. Material for -MkDocs natively integrates with [Google Analytics][1] and offers a customizable -and extendable [cookie consent][2]. +MkDocs natively integrates with [Google Analytics] and offers a customizable +and extendable [cookie consent][extra.consent]. - [1]: https://developers.google.com/analytics - [2]: #cookie-consent + [Google Analytics]: https://developers.google.com/analytics + [extra.consent]: #cookie-consent ## Configuration ### Google Analytics -:octicons-hash-24: Setting · -:octicons-milestone-24: Default: _none_ · -[:octicons-tag-24: 7.1.8][Google Analytics support] +[:octicons-tag-24: 7.1.8][Google Analytics support] · +:octicons-milestone-24: Default: _none_ 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 -the following to `mkdocs.yml`: +out Universal Analytics (`UA-*`). Depending on the property prefix, add the +following lines to `mkdocs.yml`: -=== "Google Analytics 4" +=== ":material-google-analytics: Google Analytics 4" ``` yaml extra: @@ -33,7 +32,7 @@ the following to `mkdocs.yml`: property: G-XXXXXXXXXX ``` -=== "Universal Analytics" +=== ":material-google-analytics: Universal Analytics" ``` yaml extra: @@ -43,11 +42,10 @@ the following to `mkdocs.yml`: ``` [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 -Besides basic page views, _site search_ can also be tracked to understand better +Besides basic page views, site search can also be tracked to understand better how people use your documentation and what they expect to find. To enable search tracking: @@ -57,21 +55,20 @@ search tracking: 4. Scroll down and enable __site search settings__ 5. Set the __query parameter__ to `q`. -_Site search tracking is not supported with Google Analytics 4 due to the much -more complicated manual setup. If you want to set up site search tracking -yourself, [this tutorial][4] might be a good start._ +Site search tracking is not supported with Google Analytics 4 due to the more +complicated manual setup. If you want to set up site search tracking yourself, +[this tutorial][tutorial] is a good start. - [4]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/ + [tutorial]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/ ### Cookie consent [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · -:octicons-hash-24: Setting · -:octicons-milestone-24: Default: _none_ · -[:octicons-tag-24: insiders-2.10.0][Insiders] +[:octicons-tag-24: insiders-2.10.0][Insiders] · +:octicons-milestone-24: Default: _none_ -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 +Material for MkDocs ships a native and extensible cookie consent form which +asks the user for his consent prior to sending any analytics. Add the following to `mkdocs.yml`: ``` yaml @@ -90,10 +87,10 @@ extra: Note that both, `title` and `description`, are required. If Google Analytics was configured via `mkdocs.yml`, the cookie consent will automatically include a -setting for the user to disable it. Furthermore, [custom cookies][6] can be +setting for the user to disable it. Furthermore, [custom cookies] can be integrated by using the `cookies` field: -=== "Change cookie name" +=== "Custom cookie name" ``` yaml extra: @@ -104,7 +101,7 @@ integrated by using the `cookies` field: 1. The default name of the `analytics` cookie is `Google Analytics`. -=== "Add custom cookie" +=== "Custom cookie" ``` yaml extra: @@ -119,79 +116,87 @@ integrated by using the `cookies` field: When a user first visits your site, a cookie consent form is rendered: -[![Cookie consent][7]][7] +[![extra.consent enabled]][extra.consent enabled] In order to comply with GDPR, users must be able to change their cookie settings at any time. This can be done by creating a simple link as part of any document, -e.g. privacy policy: +e.g. your privacy policy: ``` markdown [Change cookie settings](#__consent){ .md-button } ``` [Insiders]: ../insiders/index.md - [5]: ../insiders/index.md - [6]: #custom-cookies - [7]: ../assets/screenshots/consent.png + [custom cookies]: #custom-cookies + [extra.consent enabled]: ../assets/screenshots/consent.png ## Customization ### Custom site analytics -[:octicons-file-code-24: Source][3] · -:octicons-mortar-board-24: Difficulty: _moderate_ - In order to integrate another analytics service provider offering a -JavaScript-based tracking solution, you can [extend the theme][8] and add a new -`custom.html` partial [here][9]. The name of the partial can then be used to -configure the custom integration from `mkdocs.yml`: +JavaScript-based tracking solution, just follow the guide on [theme extension] +and create a new partial in the `overrides` folder. The name of the partial is +used to configure the custom integration via `mkdocs.yml`: -``` yaml -extra: - analytics: - provider: custom # (1) - key: value # (2) -``` +=== ":octicons-file-code-16: partials/integrations/analytics/custom.html" -1. Of course, you can change the name to the partial to anything you like. -2. You can add arbitrary `key` and `value` combinations to configure your custom - integration. This is especially useful if you're sharing the custom - integration across multiple repositories. + ``` html + + ``` -#### Instant loading + 1. As an example, this variable receives the value set in `mkdocs.yml`, + which is `"foobar"` for `property`. + 2. If you're using [instant loading], you can use the `location$` + observable to listen for navigation events, which always emits the + current `URL`. -If you're using [instant loading][10], you may use the `location$` observable, -which will emit the current `URL` to listen for navigation events and register -a page view event with: +=== ":octicons-file-code-16: mkdocs.yml" -``` js -location$.subscribe(function(url) { - /* Track a page event */ -}) -``` + ``` yaml + extra: + analytics: + provider: custom + property: foobar # (1) + ``` -Note that this must be integrated with [additional JavaScript][11]. + 1. You can add arbitrary key-value combinations to configure your + custom integration. This is especially useful if you're sharing the + custom integration across multiple repositories. - [10]: setting-up-navigation.md#instant-loading - [11]: ../customization.md#additional-javascript + [theme extension]: ../customization.md#extending-the-theme + [instant loading]: setting-up-navigation.md#instant-loading ### Custom cookies -[:octicons-file-code-24: Source][3] · -:octicons-mortar-board-24: Difficulty: _moderate_ +If you've customized the [cookie consent][extra.consent] and added a `custom` +cookie, the user will be prompted to accept your custom cookie. Use [additional +JavaScript] to check whether the user accepted it: -If you've customized the [cookie consent][12] and added a `custom` cookie, the -user will be prompted to accept your custom cookie. Use -[additional JavaScript][11] to check whether the user accepted it: +=== ":octicons-file-code-16: docs/javascripts/consent.js" -``` js -var consent = __md_get("__consent") -if (consent && consent.custom) { - /* The user accepted the cookie */ -} -``` + ``` js + var consent = __md_get("__consent") + if (consent && consent.custom) { + /* The user accepted the cookie */ + } + ``` - [12]: #cookie-consent +=== ":octicons-file-code-16: mkdocs.yml" + + ``` yaml + extra_javascript: + - javascripts/consent.js + ``` + + [additional JavaScript]: ../customization.md#additional-javascript diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 819fa2a04..5c9210deb 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -37,9 +37,9 @@ plugins: The following options are supported: -`lang`{ #lang } +`lang`{ #search-lang } -: :octicons-milestone-24: Default: _auto_ – This option allows +: :octicons-milestone-24: Default: _automatically set_ – This option allows to include the language-specific stemmers provided by [lunr-languages][5]. Note that Material for MkDocs will set this automatically based on the [site language][6], but it may be overridden, e.g. to support multiple @@ -98,9 +98,9 @@ The following options are supported: JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb per language. -`separator`{ #separator } +`separator`{ #search-separator } -: :octicons-milestone-24: Default: _auto_ – The separator for +: :octicons-milestone-24: Default: _automatically set_ – The separator for indexing and query tokenization can be customized, making it possible to index parts of words separated by other characters than whitespace and `-`, e.g. by including `.`: @@ -111,7 +111,7 @@ The following options are supported: separator: '[\s\-\.]+' ``` -~~`prebuild_index`~~{ #prebuild-index }[^1] +~~`prebuild_index`~~{ #search-prebuild-index }[^1] : :octicons-milestone-24: Default: `false` · :octicons-archive-24: Deprecated – MkDocs can generate a [prebuilt index][7] of all pages during diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index b5cd261cc..f19b4838a 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -6,8 +6,8 @@ template: overrides/main.html Social cards, also known as social previews, are images that are displayed when a link to your project documentation is shared on social media. Material for -MkDocs can generate beautiful social cards automatically, using the [colors][1], -[fonts][2] and [logo][3][^1] defined in `mkdocs.yml`. +MkDocs can generate beautiful social cards automatically, using the [colors] +[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`. [^1]: Both types of logos, images (`theme.logo`) and icons (`theme.icon.logo`) @@ -15,69 +15,66 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1], color used in the header (white or black), which depends on the primary color. - [1]: changing-the-colors.md#primary-color - [2]: changing-the-fonts.md#regular-font - [3]: changing-the-logo-and-icons.md#logo + [palette.primary]: changing-the-colors.md#primary-color + [font.text]: changing-the-fonts.md#regular-font + [logo]: changing-the-logo-and-icons.md#logo ## Configuration ### Built-in social cards [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.12.0][Insiders] · :octicons-cpu-24: Plugin · -:octicons-beaker-24: Experimental · -[:octicons-tag-24: insiders-2.12.0][Insiders] +:octicons-beaker-24: Experimental -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 -shared. Enable it via `mkdocs.yml`: +The built-in social cards plugin generates a social preview image for every page +and adds the necessary meta tags, so it's displayed on social media when shared. +Enable it via `mkdocs.yml`: ``` yaml plugins: - social ``` -For example, the page on [setting up site analytics][5] renders as: +For example, the page on [setting up site analytics] renders as:
-[![Social Cards][6]][6] +[![Social cards preview]][Social cards preview]
Want to try it out? Copy the current URL and paste it into [Twitter's Card -validator][7] to see how social cards look in action. +validator] to see how social cards look in action.
-This is a built-in plugin, which means that no third-party plugin needs to be -installed, as Material for MkDocs already bundles it. The following options -are available: +The following configuration options are available: -`cards_color`{ #cards-color } :material-new-box: +`cards_color`{ #cards-color } -: :octicons-milestone-24: Default: [`primary - color`][8]_ – This option specifies which colors to use for the background - `fill` and foreground `text` when generating the social card. +: :octicons-milestone-24: Default: [primary color][palette.primary] + header + text color – This option specifies which colors to use for the background + `fill` and foreground `text` when generating the social card: ``` yaml plugins: - social: cards_color: - fill: "#0FF1CE" + fill: "#0FF1CE" # (1) text: "#FFFFFF" ``` - Note that the values for `fill` and `text` can either be HEX color values - (e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g. - `red`, `green`, etc.). + 1. Colors can either be defined as HEX colors, or as [CSS color keywords]. + Note that HEX colors must be enclosed in quotes. `cards_directory`{ #cards-directory } : :octicons-milestone-24: Default: `assets/images/social` – This option - specifies where the generated social card images will be written to. It - should normally not be necessary to change this option. + specifies where the generated social card images will be written to. It's + normally not necessary to change this option: ``` yaml plugins: @@ -86,24 +83,23 @@ are available: ``` [Insiders]: ../insiders/index.md - [4]: ../insiders/index.md - [5]: setting-up-site-analytics.md - [6]: ../assets/screenshots/social-cards.png - [7]: https://cards-dev.twitter.com/validator - [8]: changing-the-colors.md#primary-color + [setting up site analytics]: setting-up-site-analytics.md + [Social cards preview]: ../assets/screenshots/social-cards.png + [Twitter's Card validator]: https://cards-dev.twitter.com/validator + [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords -#### Caching +#### Caching recommended { data-toc-label="Caching" } -When enabled, the [social cards plugin][9] automatically fetches the fonts you -define in `mkdocs.yml` from Google Fonts, and uses them to render the text that -is displayed on the social card. The font files and generated cards are both +The [built-in social cards plugin] automatically fetches the fonts you define +in `mkdocs.yml` from Google Fonts, and uses them to render the text that is +displayed on the social card. The font files and generated cards are both written to the `.cache` directory, which is used in subsequent builds to detect whether the social cards need to be regenerated. You might want to: 1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`. 2. When building your site for publishing, use a build cache to save the `.cache` directory in between builds. Taking the example from the - [publishing guide][10], add the following lines: + [publishing guide], add the following lines: ``` yaml hl_lines="15-18" name: ci @@ -128,27 +124,14 @@ whether the social cards need to be regenerated. You might want to: - run: mkdocs gh-deploy --force ``` - [9]: #built-in-social-cards - [10]: ../publishing-your-site.md#with-github-actions + [built-in social cards plugin]: #built-in-social-cards + [publishing guide]: ../publishing-your-site.md#with-github-actions -## Usage +#### Meta tags -If you want to adjust the title or set a custom description for the social card, -you can use the [Metadata][11] extension, which takes precedence over the -default values. - -- [Changing the title][12] -- [Changing the description][13] - - [11]: ../reference/meta-tags.md#metadata - [12]: ../reference/meta-tags.md#setting-the-page-title - [13]: ../reference/meta-tags.md#setting-the-page-description - -### Using social media meta tags - -The [built-in social cards plugin] generates beautiful image previews for social -media during the build and sets all necessary `meta` tags, equivalent to the -following two customizations: +The [built-in social cards plugin] automatically sets all necessary `meta` tags, +equivalent to the following two customizations, which you can set manually when +you don't want to use it: === ":material-graph: Open Graph" @@ -158,7 +141,7 @@ following two customizations: {% if page and page.meta and page.meta.title %} {% set title = title ~ " - " ~ page.meta.title %} {% elif page and page.title and not page.is_homepage %} - {% set title = title ~ " - " ~ page.title | striptags %} + {% set title = title ~ " - " ~ page.title %} {% endif %} @@ -179,11 +162,9 @@ following two customizations: {% if page and page.meta and page.meta.title %} {% set title = title ~ " - " ~ page.meta.title %} {% elif page and page.title and not page.is_homepage %} - {% set title = title ~ " - " ~ page.title | striptags %} + {% set title = title ~ " - " ~ page.title %} {% endif %} - - @@ -192,3 +173,17 @@ following two customizations: [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards [built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards + + +## Usage + +If you want to adjust the title or set a custom description for the social card, +you can use the [Metadata] extension, which takes precedence over the +default values. + +- [Changing the title] +- [Changing the description] + + [Metadata]: extensions/python-markdown.md#metadata + [Changing the title]: ../reference/meta-tags.md#setting-the-page-title + [Changing the description]: ../reference/meta-tags.md#setting-the-page-description diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 687138583..7d88aed9a 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -14,11 +14,11 @@ can help to discover relevant information faster. ### Built-in tags [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-2.7.0][Insiders] · :octicons-cpu-24: Plugin · -:octicons-beaker-24: Experimental · -[:octicons-tag-24: insiders-2.7.0][Insiders] +:octicons-beaker-24: Experimental -The [built-in tags plugin][1] adds the ability to categorize any page with tags +The built-in tags plugin 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 the following lines to `mkdocs.yml`: @@ -27,15 +27,13 @@ plugins: - tags ``` -Note that no third-party plugin[^1] needs to be installed, as Material for -MkDocs provides its own implementation to allow for a meaningful integration. -The following options are available: +The following configuration options are available: `tags_file`{ #tags-file } : :octicons-milestone-24: Default: _none_ – This option specifies which file should be used to render the tags index. See the section on [adding a tags - index][3] for more information. If this option is specified, tags will + index] for more information. If this option is specified, tags will become clickable, pointing to the corresponding section in the tags index: ``` yaml @@ -49,29 +47,18 @@ The following options are available: option is not specified, tags are still rendered and searchable, but without a tags index. - [^1]: - The built-in tags plugin has no affiliation with [mkdocs-plugin-tags][2], - another option to add tag support to MkDocs, which has several caveats: - it requires a `title` set in the front matter for every page for which tags - should be added, doesn't support all syntactic flavors of front matter, - doesn't integrate tags in search and doesn't render tags on pages without - 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 + [adding a tags index]: #adding-a-tags-index ## Usage ### Adding tags -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: +When both, the [built-in tags plugin] and [Metadata] extension are enabled, +tags can be added for a document with custom front matter. Add the following +lines at the top of a Markdown file: -``` yaml +``` bash --- tags: - insiders @@ -87,22 +74,22 @@ following screenshots: === "Tags" - [![Tags][6]][6] + [![Tags preview]][Tags preview] === "Tag search" - [![Tag search][7]][7] + [![Tag search preview]][Tag search preview] - [4]: #built-in-tags - [5]: ../../reference/meta-tags/#metadata - [6]: ../assets/screenshots/tags.png - [7]: ../assets/screenshots/tags-search.png + [built-in tags plugin]: #built-in-tags + [Metadata]: extensions/python-markdown.md#metadata + [Tags preview]: ../assets/screenshots/tags.png + [Tag search preview]: ../assets/screenshots/tags-search.png ### Adding a tags index -The [built-in tags plugin][4] allows to define a file to render a [tags -index][8], which can be any page that is part of the `nav` section. To add a -tags index, create a page, e.g. `tags.md`: +The [built-in tags plugin] allows to define a file to render a [tags index] +[tags.tags_file], which can be any page that is part of the `nav` section. To +add a tags index, create a page, e.g. `tags.md`: ``` markdown # Tags @@ -118,14 +105,14 @@ arbitrary content before and after the marker: [![Tags index][9]][9] - [8]: #tags_file + [tags.tags_file]: #tags-file [9]: ../assets/screenshots/tags-index.png ### Hiding the tags 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: +[Metadata] extension: ``` bash --- @@ -136,5 +123,3 @@ hide: # Document title ... ``` - - [10]: ../../reference/meta-tags/#metadata diff --git a/docs/setup/setting-up-the-footer.md b/docs/setup/setting-up-the-footer.md index e3a927687..90d14fe63 100644 --- a/docs/setup/setting-up-the-footer.md +++ b/docs/setup/setting-up-the-footer.md @@ -32,7 +32,7 @@ extra: For each entry, the following settings are available: -`icon`{ #icon } +`icon`{ #social-icon } : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – This field must point to a valid icon path referencing [any icon bundled @@ -53,7 +53,7 @@ For each entry, the following settings are available: [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons -`link`{ #link } +`link`{ #social-link } : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – This field must contain a valid relative or absolute URL including the URI @@ -77,7 +77,7 @@ For each entry, the following settings are available: link: mailto: ``` -`name`{ #name } +`name`{ #social-name } : :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ – This field is used as the link's `title` attribute and can be set to a diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md index 9f94182c3..d15129eb8 100644 --- a/docs/setup/setting-up-versioning.md +++ b/docs/setup/setting-up-versioning.md @@ -6,21 +6,21 @@ template: overrides/main.html Material for MkDocs makes it easy to deploy multiple versions of your project documentation by integrating with external utilities that add those capabilities -to MkDocs, i.e. [mike][1]. When deploying a new version, older versions of your +to MkDocs, i.e. [mike]. When deploying a new version, older versions of your documentation remain untouched. - [1]: https://github.com/jimporter/mike + [mike]: https://github.com/jimporter/mike ## Configuration ### Versioning -[:octicons-file-code-24: Source][2] · -[:octicons-package-24: Utility][1] +[:octicons-tag-24: 7.0.0][version support] · +[:octicons-package-24: Utility][mike] -[mike][1] makes it easy to deploy multiple versions of your project -documentation. It integrates natively with Material for MkDocs and can be -enabled via `mkdocs.yml`: +[mike] makes it easy to deploy multiple versions of your project documentation. +It integrates natively with Material for MkDocs and can be enabled via +`mkdocs.yml`: ``` yaml extra: @@ -28,22 +28,21 @@ extra: provider: mike ``` -This will render a version selector in the header next to the title of your -project: +This renders a version selector in the header:
-[![Version selection][3]][3] +[![Version selector preview]][Version selector preview]
-A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-example-versioning][4] +Check out the versioning example to see it in action – +[squidfunk.github.io/mkdocs-material-example-versioning][version example]
-!!! quote "[Why use mike?][5]" +!!! quote "[Why use mike?]" mike is built around the idea that once you've generated your docs for a particular version, you should never need to touch that version again. This @@ -56,15 +55,10 @@ A demo is worth a thousand words — check it out at to particularly notable versions. This makes it easy to make permalinks to whatever version of the documentation you want to direct people to. -_Note that you don't need to run_ `mike install-extras` _as noted in the -[official documentation][6], as [mike][1] is now natively integrated with -Material for MkDocs._ - - [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html - [3]: ../assets/screenshots/versioning.png - [4]: https://squidfunk.github.io/mkdocs-material-example-versioning/ - [5]: https://github.com/jimporter/mike#why-use-mike - [6]: https://github.com/jimporter/mike#usage + [version support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 + [Version selector preview]: ../assets/screenshots/versioning.png + [version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/ + [Why use mike?]: https://github.com/jimporter/mike#why-use-mike ### Version warning