OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-10 21:04:22 +02:00
parent a0ff73932f
commit 6acd637cb8
11 changed files with 97 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/customization.md
View File

@ -152,7 +152,7 @@ directory:
MkDocs will now use the new partial when rendering the theme. This can be done MkDocs will now use the new partial when rendering the theme. This can be done
with any file. with any file.
### Overriding blocks <small>recommended</small> { data-toc-label="Overriding blocks" } ### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="Overriding blocks" }
Besides overriding partials, it's also possible to override (and extend) Besides overriding partials, it's also possible to override (and extend)
_template blocks_, which are defined inside the templates and wrap specific _template blocks_, which are defined inside the templates and wrap specific
@ -216,7 +216,7 @@ with Material for MkDocs_ hint in the footer, add the following line to
{% extends "base.html" %} {% extends "base.html" %}
{% set extracopyright %} {% set extracopyright %}
<!-- Add your additional information here --> <!-- Add additional copyright information here -->
{% endset %} {% endset %}
``` ```

2
docs/deprecations.md
View File

@ -124,7 +124,7 @@ templates can be shared among multiple pages:
{% endblock %} {% endblock %}
``` ```
[5]: customization.md#overriding-blocks-recommended [5]: customization.md#overriding-blocks
[6]: customization.md#extending-the-theme [6]: customization.md#extending-the-theme
## Docker image ## Docker image

2
docs/getting-started.md
View File

@ -19,7 +19,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
## Installation ## Installation
### with pip <small>recommended</small> { data-toc-label="with pip" } ### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
Material for MkDocs can be installed with `pip`: Material for MkDocs can be installed with `pip`:

4
docs/reference/meta-tags.md
View File

@ -105,7 +105,7 @@ extra:
#### on all pages #### on all pages
In order to add custom `meta` tags to your document, you can [extend the theme In order to add custom `meta` tags to your document, you can [extend the theme
][theme extension] and [override the `extrahead` block][override block], ][theme extension] and [override the `extrahead` block][overriding blocks],
e.g. to add indexing policies for search engines via the `robots` property: e.g. to add indexing policies for search engines via the `robots` property:
``` html ``` html
@ -116,7 +116,7 @@ e.g. to add indexing policies for search engines via the `robots` property:
{% endblock %} {% endblock %}
``` ```
[override block]: ../customization.md#overriding-blocks-recommended [overriding blocks]: ../customization.md#overriding-blocks
#### on a single page #### on a single page

49
docs/setup/adding-a-comment-system.md
View File

@ -4,47 +4,43 @@ template: overrides/main.html
# Adding a comment system # Adding a comment system
Material for MkDocs is natively integrated with [Disqus][1], a comment system Material for MkDocs is natively integrated with [Disqus], a comment system that
that provides a wide range of features like social integrations, user profiles, provides a wide range of features like social integrations, user profiles, as
as well as spam and moderation tools. Of course, other comment systems can be well as spam and moderation tools. Of course, other comment systems can be
integrated, too. integrated, too.
[1]: https://disqus.com/ [Disqus]: https://disqus.com/
## Configuration ## Configuration
### Disqus ### Disqus
[:octicons-file-code-24: Source][2] · [:octicons-tag-24: 1.1.0][Disqus support] ·
:octicons-milestone-24: Default: _none_ :octicons-milestone-24: Default: _none_
First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`. Then, to
Material for MkDocs with [Disqus][1], create an account and a site giving you a integrate Material for MkDocs with [Disqus], create an account and a site
[shortname][4], and add it to `mkdocs.yml`: giving you a [shortname], and add it to `mkdocs.yml`:
``` yaml ``` yaml
extra: extra:
disqus: <shortname> disqus: <shortname>
``` ```
This will insert a comment system on _every page, except the index page_. This will insert a comment system on every page, except the index page.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html [Disqus support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[3]: https://www.mkdocs.org/user-guide/configuration/#site_url [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname [shortname]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
## Customization ## Customization
### Selective integration ### Selective integration
[:octicons-file-code-24: Source][2] · When [Metadata] is enabled, Disqus can be enabled or disabled for a document
:octicons-note-24: Metadata · with custom front matter. Add the following lines at the top of a Markdown file:
:octicons-mortar-board-24: Difficulty: _easy_
If the [Metadata][5] extension is enabled, you can disable or enable Disqus for === ":octicons-check-circle-fill-16: Enabled"
specific pages by adding the following to the front matter of a page:
=== "Enable Disqus"
``` bash ``` bash
--- ---
@ -55,7 +51,7 @@ specific pages by adding the following to the front matter of a page:
... ...
``` ```
=== "Disable Disqus" === ":octicons-skip-16: Disabled"
``` bash ``` bash
--- ---
@ -66,15 +62,13 @@ specific pages by adding the following to the front matter of a page:
... ...
``` ```
[5]: ../../reference/meta-tags/#metadata [Metadata]: extensions/python-markdown.md#metadata
### Other comment systems ### Other comment systems
[:octicons-file-code-24: Source][6] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to integrate another JavaScript-based comment system provider, you can In order to integrate another JavaScript-based comment system provider, you can
[extend the theme][7] and [override the `disqus` block][8]: [extend the theme], create a new `main.html` in `overrides` and [override the
`disqus` block][overriding blocks]:
``` html ``` html
{% extends "base.html" %} {% extends "base.html" %}
@ -84,6 +78,5 @@ In order to integrate another JavaScript-based comment system provider, you can
{% endblock %} {% endblock %}
``` ```
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html [extend the theme]: ../customization.md#extending-the-theme
[7]: ../customization.md#extending-the-theme [overriding blocks]: ../customization.md#overriding-blocks
[8]: ../customization.md#overriding-blocks-recommended

2
docs/setup/setting-up-site-analytics.md
View File

@ -20,7 +20,7 @@ and extendable [cookie consent][extra.consent].
:octicons-milestone-24: Default: _none_ :octicons-milestone-24: Default: _none_
Material for MkDocs integrates with both, Google Analytics 4 and the now phasing Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
out Universal Analytics (`UA-*`). Depending on the property prefix, add the out Universal Analytics. Depending on the given property prefix, add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
=== ":material-google-analytics: Google Analytics 4" === ":material-google-analytics: Google Analytics 4"

8
docs/setup/setting-up-site-search.md
View File

@ -150,7 +150,7 @@ Use them at your own risk._
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search suggestions support] [:octicons-tag-24: 7.2.0][Search suggestions support]
When _search suggestions_ are enabled, the search will display the likeliest 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 completion for the last word, saving the user many key strokes by accepting the
suggestion with the ++arrow-right++ key. suggestion with the ++arrow-right++ key.
@ -177,7 +177,7 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search highlighting support] [:octicons-tag-24: 7.2.0][Search highlighting support]
When _search highlighting_ is enabled and a user clicks on a search result, When search highlighting is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link. Material for MkDocs will highlight all occurrences after following the link.
Add the following lines to `mkdocs.yml`: Add the following lines to `mkdocs.yml`:
@ -202,7 +202,7 @@ Searching for [:octicons-search-24: code blocks][12] yields:
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0][Search highlighting support] [:octicons-tag-24: 7.2.0][Search highlighting support]
When _search sharing_ is activated, a :material-share-variant: share button is 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 rendered next to the reset button, which allows to deep link to the current
search query and result. Add the following lines to `mkdocs.yml`: search query and result. Add the following lines to `mkdocs.yml`:
@ -439,7 +439,7 @@ and must return the processed query string to be submitted to the search index.
[23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[24]: ../customization.md#extending-the-theme [24]: ../customization.md#extending-the-theme
[25]: ../customization.md#overriding-blocks-recommended [25]: ../customization.md#overriding-blocks
### Custom search ### Custom search

11
docs/setup/setting-up-social-cards.md
View File

@ -30,7 +30,12 @@ MkDocs can generate beautiful social cards automatically, using the [colors]
The built-in social cards plugin generates a social preview image for every page 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. and adds the necessary meta tags, so it's displayed on social media when shared.
Enable it via `mkdocs.yml`: First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`.[^2] Then, add
the following lines to `mkdocs.yml` to enable the plugin:
[^2]:
When using this plugin, the [`site_url`][site_url] setting is mandatory, as
social preview images don't work with relative URLs.
``` yaml ``` yaml
plugins: plugins:
@ -83,12 +88,14 @@ The following configuration options are available:
``` ```
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[setting up site analytics]: setting-up-site-analytics.md [setting up site analytics]: setting-up-site-analytics.md
[Social cards preview]: ../assets/screenshots/social-cards.png [Social cards preview]: ../assets/screenshots/social-cards.png
[Twitter's Card validator]: https://cards-dev.twitter.com/validator [Twitter's Card validator]: https://cards-dev.twitter.com/validator
[meta tags]: #meta-tags
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
#### Caching <small>recommended</small> { data-toc-label="Caching" } #### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
The [built-in social cards plugin] automatically fetches the fonts you define 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 in `mkdocs.yml` from Google Fonts, and uses them to render the text that is

50
docs/setup/setting-up-the-footer.md
View File

@ -15,9 +15,8 @@ configured via `mkdocs.yml`.
### Social links ### Social links
:octicons-hash-24: Setting · [:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_ · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 1.0.0][Social links support]
Social links are rendered next to the copyright notice 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` footer of your project documentation. Add a list of social links in `mkdocs.yml`
@ -36,7 +35,8 @@ For each entry, the following settings are available:
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled This field must point to a valid icon path referencing [any icon bundled
with the theme][2], or the build will not succeed. Some popular choices: with the theme][custom icons], or the build will not succeed. Some popular
choices:
* :fontawesome-brands-behance: – `fontawesome/brands/behance` * :fontawesome-brands-behance: – `fontawesome/brands/behance`
* :fontawesome-brands-docker: – `fontawesome/brands/docker` * :fontawesome-brands-docker: – `fontawesome/brands/docker`
@ -50,8 +50,7 @@ For each entry, the following settings are available:
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter` * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [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 [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
`link`{ #social-link } `link`{ #social-link }
@ -59,7 +58,7 @@ For each entry, the following settings are available:
This field must contain a valid relative or absolute URL including the URI This field must contain a valid relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`: scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== "Twitter" === ":fontawesome-brands-twitter: Twitter"
``` yaml ``` yaml
extra: extra:
@ -68,7 +67,7 @@ For each entry, the following settings are available:
link: https://twitter.com/squidfunk link: https://twitter.com/squidfunk
``` ```
=== "Email address" === ":octicons-mail-16: Email"
``` yaml ``` yaml
extra: extra:
@ -93,9 +92,8 @@ For each entry, the following settings are available:
### Copyright notice ### Copyright notice
:octicons-hash-24: Setting · [:octicons-tag-24: 0.1.0][Copyright notice support] ·
:octicons-milestone-24: Default: _none_ · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 0.1.0][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`: displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@ -109,9 +107,8 @@ copyright: Copyright &copy; 2016 - 2020 Martin Donath
### Generator notice ### Generator notice
:octicons-hash-24: Setting · [:octicons-tag-24: 7.3.0][Generator notice support] ·
:octicons-milestone-24: Default: `true` · :octicons-milestone-24: Default: `true`
[:octicons-tag-24: 7.3.0][Generator notice support]
The footer displays a _Made with Material for MkDocs_ notice to denote how 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 the site was generated. The notice can be removed with the following setting
@ -127,25 +124,24 @@ extra:
The subtle __Made with Material for MkDocs__ hint in the footer is one of The subtle __Made with Material for MkDocs__ hint in the footer is one of
the reasons why this project is so popular, as it tells the user how the the reasons why this project is so popular, as it tells the user how the
site is generated, helping new users to discover this project. Before site is generated, helping new users to discover this project. Before
removing it, please consider that you're enjoying the benefits of removing please consider that you're enjoying the benefits of @squidfunk's
@squidfunk's work for free, as this project is Open Source and has a work for free, as this project is Open Source and has a permissive license.
permissive license. Thousands of hours went into this project, most of them Thousands of hours went into this project, most of them
without any financial return. Thus, if you remove this notice, please without any financial return.
consider [sponsoring][4] the project. __Thank you__
:octicons-heart-fill-24:{ .mdx-heart .mdx-insiders } Thus, if you remove this notice, please consider [sponsoring][Insiders] the
project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
[Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Insiders]: ../insiders/index.md
## Customization ## Customization
### Custom icons ### Custom icons
[:octicons-file-code-24: Source][2] · The social links feature uses the standard [icon integration] of Material for
:octicons-mortar-board-24: Difficulty: _easy_
The social links feature uses the standard [icon integration][5] of Material for
MkDocs. If you want to use custom icons, follow the guide explaining how to MkDocs. If you want to use custom icons, follow the guide explaining how to
add [additional icons][6]. add [additional icons].
[5]: changing-the-logo-and-icons.md#icons [icon integration]: extensions/python-markdown-extensions.md#emoji
[6]: changing-the-logo-and-icons.md#additional-icons [additional icons]: changing-the-logo-and-icons.md#additional-icons

31
docs/setup/setting-up-the-header.md
View File

@ -6,20 +6,20 @@ template: overrides/main.html
Material for MkDocs' header can be customized to show an announcement bar that Material for MkDocs' header can be customized to show an announcement bar that
disappears upon scrolling, and provides some options for further configuration. disappears upon scrolling, and provides some options for further configuration.
It also includes the [search bar][1] and a place to display your project's It also includes the [search bar] and a place to display your project's
[git repository][2], as explained in those dedicated guides. [git repository], as explained in those dedicated guides.
[1]: setting-up-site-search.md [search bar]: setting-up-site-search.md
[2]: adding-a-git-repository.md [git repository]: adding-a-git-repository.md
## Configuration ## Configuration
### Automatic hiding ### Automatic hiding
:octicons-unlock-24: Feature flag · [:octicons-tag-24: 6.2.0][Automatic hiding support] ·
[:octicons-tag-24: 6.2.0][Automatic hiding support] :octicons-unlock-24: Feature flag
When _autohiding_ is enabled, the header is automatically hidden when the When autohiding is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the user scrolls past a certain threshold, leaving more space for content. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
@ -31,28 +31,25 @@ theme:
[Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 [Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
## Customization
### Announcement bar ### Announcement bar
:octicons-file-symlink-file-24: Customization · [:octicons-tag-24: 5.0.0][Announcement bar support] ·
[:octicons-tag-24: 5.0.0][Announcement bar support] :octicons-file-symlink-file-24: Customization
Material for MkDocs includes an announcement bar, which is the perfect place to 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 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 scrolls past the header, the bar will automatically disappear. In order to add
an announcement bar, [extend the theme][4] and [override the `announce` an announcement bar, [extend the theme] and [override the `announce`
block][5], which is empty by default: block][overriding blocks], which is empty by default:
``` html ``` html
{% extends "base.html" %} {% extends "base.html" %}
{% block announce %} {% block announce %}
<!-- Add your announcement here, including arbitrary HTML --> <!-- Add announcement here, including arbitrary HTML -->
{% endblock %} {% endblock %}
``` ```
[Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 [Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[extend the theme]: ../customization.md#extending-the-theme
[4]: ../customization.md#extending-the-theme [overriding blocks]: ../customization.md#overriding-blocks
[5]: ../customization.md#overriding-blocks-recommended

49
docs/setup/setting-up-versioning.md
View File

@ -63,12 +63,12 @@ Check out the versioning example to see it in action –
### Version warning ### Version warning
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .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][Insiders] ·
[:octicons-tag-24: insiders-2.5.0][Insiders] :octicons-file-symlink-file-24: Customization
If you're using versioning, you might want to display a warning when the user 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], visits any other version than the latest version. Using [theme extension],
you can [define the `outdated` block][9]: you can [override the `outdated` block][overriding blocks]:
``` html ``` html
{% extends "base.html" %} {% extends "base.html" %}
@ -89,11 +89,11 @@ you can [define the `outdated` block][9]:
This will render a version warning above the header: This will render a version warning above the header:
[![Version warning][10]][10] [![Version warning preview]][Version warning preview]
By default, the default version is identified by the `latest` alias. If you The default version is identified by the `latest` alias. If you wish to set
wish to set another alias as the latest version, e.g. `stable`, add the another alias as the latest version, e.g. `stable`, add the following lines
following to `mkdocs.yml`: to `mkdocs.yml`:
``` yaml ``` yaml
extra: extra:
@ -101,14 +101,13 @@ extra:
default: stable default: stable
``` ```
Make sure that this matches the [default version][11]. Make sure that this matches the [default version].
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[7]: ../insiders/index.md [theme extension]: ../customization.md#extending-the-theme
[8]: ../customization.md#extending-the-theme [overriding blocks]: ../customization.md#overriding-blocks
[9]: ../customization.md#overriding-blocks-recommended [Version warning preview]: ../assets/screenshots/version-warning.png
[10]: ../assets/screenshots/version-warning.png [default version]: #setting-a-default-version
[11]: #setting-a-default-version
### Stay on page ### Stay on page
@ -135,21 +134,11 @@ the current page:
docs.example.com/0.1/bar/ -> docs.example.com/0.2/ docs.example.com/0.1/bar/ -> docs.example.com/0.2/
``` ```
<figure markdown>
<figcaption markdown>
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-example-versioning][4]
</figcaption>
</figure>
## Usage ## Usage
While this section outlines the basic workflow for publishing new versions, While this section outlines the basic workflow for publishing new versions,
it's best to check out the [official documentation][6] to make yourself familar it's best to check out [mike's documentation][mike] to make yourself familar
with [mike][1]. with its mechanics.
### Publishing a new version ### Publishing a new version
@ -169,15 +158,15 @@ e.g.:
### Setting a default version ### Setting a default version
When starting with [mike][1], a good idea is to set an alias as a default When starting with [mike], a good idea is to set an alias as a default version,
version, e.g. `latest`, and when publishing a new version, always update the e.g. `latest`, and when publishing a new version, always update the alias to
alias to point to the latest version: point to the latest version:
``` ```
mike set-default --push latest mike set-default --push latest
``` ```
When publishing a new version, [mike][1] will create a redirect in the root of When publishing a new version, [mike] will create a redirect in the root of
your project documentation to the version associated with the alias: your project documentation to the version associated with the alias:
_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_ _docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_