| @@ -0,0 +1,171 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Data tables | ||
|
|
||
| Material for MkDocs defines default styles for data tables – an excellent way | ||
| of rendering tabular data in project documentation. Furthermore, customizations | ||
| like [sortable tables][1] can be achieved with a third-party library and some | ||
| [additional JavaScript][2]. | ||
|
|
||
| [1]: #sortable-tables | ||
| [2]: ../customization.md#additional-javascript | ||
|
|
||
| ## Configuration | ||
|
|
||
| None. | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using data tables | ||
|
|
||
| Data tables can be used at any position in your project documentation and can | ||
| contain arbitrary Markdown, including inline code blocks, as well as [icons and | ||
| emojis][3]. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| | Method | Description | | ||
| | ----------- | ------------------------------------ | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| | Method | Description | | ||
| | ----------- | ------------------------------------ | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
|
|
||
| [3]: icons-emojis.md | ||
|
|
||
| ### Column alignment | ||
|
|
||
| If you want to align a specific column to the `left`, `center` or `right`, you | ||
| can use the [regular Markdown syntax][4] placing `:` characters at the beginning | ||
| and/or end of the divider. | ||
|
|
||
| === "Left" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown hl_lines="2" | ||
| | Method | Description | | ||
| | :---------- | :----------------------------------- | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| | Method | Description | | ||
| | :---------- | :----------------------------------- | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
|
|
||
| === "Center" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown hl_lines="2" | ||
| | Method | Description | | ||
| | :---------: | :----------------------------------: | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| | Method | Description | | ||
| | :---------: | :----------------------------------: | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
|
|
||
| === "Right" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown hl_lines="2" | ||
| | Method | Description | | ||
| | ----------: | -----------------------------------: | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| | Method | Description | | ||
| | ----------: | -----------------------------------: | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
|
|
||
| [4]: https://www.markdownguide.org/extended-syntax/#tables | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Sortable tables | ||
|
|
||
| If you want to make data tables sortable, you can add [tablesort][5], which is | ||
| natively integrated with Material for MkDocs and will also work with [instant | ||
| loading][6] via [additional JavaScript][2]: | ||
|
|
||
| === "docs/javascripts/tables.js" | ||
|
|
||
| ``` js | ||
| app.document$.subscribe(function() { | ||
| var tables = document.querySelectorAll("article table") | ||
| tables.forEach(function(table) { | ||
| new Tablesort(table) | ||
| }) | ||
| }) | ||
| ``` | ||
|
|
||
| === "mkdocs.yml" | ||
|
|
||
| ``` yaml | ||
| extra_javascript: | ||
| - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js | ||
| - javascripts/tables.js | ||
| ``` | ||
|
|
||
| _Note that [tablesort][5] provides alternative comparison implementations like | ||
| numbers, dates, filesizes and month names. See the official documentation for | ||
| more information._ | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| | Method | Description | | ||
| | ----------- | ------------------------------------ | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| | Method | Description | | ||
| | ----------- | ------------------------------------ | | ||
| | `GET` | :material-check: Fetch resource | | ||
| | `PUT` | :material-check-all: Update resource | | ||
| | `DELETE` | :material-close: Delete resource | | ||
|
|
||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js"></script> | ||
| <script> | ||
| var tables = document.querySelectorAll("article table") | ||
| new Tablesort(tables.item(tables.length - 1)); | ||
| </script> | ||
|
|
||
| [5]: http://tristen.ca/tablesort/demo/ | ||
| [6]: ../setup/setting-up-navigation.md#instant-loading |
| @@ -0,0 +1,91 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Footnotes | ||
|
|
||
| Footnotes are a great way to add references to supplemental or additional | ||
| information for a specific section of a document without interrupting the | ||
| document flow. Material for MkDocs provides the ability to insert inline | ||
| footnotes and render them at the bottom of the page. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Footnotes | ||
|
|
||
| [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] | ||
|
|
||
| The [Footnotes][2] extension, which is part of the standard Markdown library, | ||
| adds the ability to add inline footnotes to a document and can be enabled via | ||
| `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - footnotes | ||
| ``` | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss | ||
| [2]: https://python-markdown.github.io/extensions/footnotes/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Adding footnote references | ||
|
|
||
| A footnote reference must be enclosed in square brackets and must start with a | ||
| caret `^`, directly followed by an arbitrary identifier, which is similar to | ||
| the standard Markdown link syntax. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] | ||
|
|
||
| ### Adding footnote content | ||
|
|
||
| The footnote content must be declared with the same identifier as the reference. | ||
| It can be inserted at an arbitrary position in the document and is always | ||
| rendered at the bottom of the page. Furthermore, a backlink to the footnote | ||
| reference is automatically added. | ||
|
|
||
| #### on a single line | ||
|
|
||
| Short statements can be written on the same line. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| [Jump to footnote at the bottom of the page](#fn:1) | ||
|
|
||
| [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. | ||
|
|
||
| #### on multiple lines | ||
|
|
||
| Paragraphs can be written on the next line and must be indented by four spaces. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| [^2]: | ||
| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod | ||
| nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor | ||
| massa, nec semper lorem quam in massa. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| [^2]: | ||
| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod | ||
| nulla. Curabitur feugiat, tortor non consequat finibus, justo purus | ||
| auctor massa, nec semper lorem quam in massa. | ||
|
|
||
| [Jump to footnote at the bottom of the page](#fn:2) |
| @@ -0,0 +1,189 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Formatting | ||
|
|
||
| Material for MkDocs provides support for several HTML elements that can be used | ||
| to highlight sections of a document or apply specific formatting. Additionally, | ||
| [Critic Markup][1] is supported, adding the ability to display suggested changes | ||
| for a document. | ||
|
|
||
| [1]: http://criticmarkup.com/ | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Critic | ||
|
|
||
| [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] | ||
|
|
||
| The [Critic][3] extension, which is part of [Python Markdown Extensions][4], | ||
| allows for the __usage of [Critic Markup][1] to highlight changes__ in a | ||
| document, and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.critic | ||
| ``` | ||
|
|
||
| The following options are supported: | ||
|
|
||
| `mode`{: #mode } | ||
|
|
||
| : :octicons-milestone-24: Default: `view` – This option defines how the markup | ||
| should be parsed, i.e. whether to just `view` all suggest changes, or | ||
| alternatively `accept` or `reject` them: | ||
|
|
||
| === "View changes" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.critic: | ||
| mode: view | ||
| ``` | ||
|
|
||
| === "Accept changes" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.critic: | ||
| mode: accept | ||
| ``` | ||
|
|
||
| === "Reject changes" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.critic: | ||
| mode: reject | ||
| ``` | ||
|
|
||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss | ||
| [3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/ | ||
| [4]: https://facelessuser.github.io/pymdown-extensions/ | ||
|
|
||
| ### BetterEm | ||
|
|
||
| The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4], | ||
| improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_), | ||
| and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.betterem: | ||
| smart_enable: all | ||
| ``` | ||
|
|
||
| [5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/ | ||
|
|
||
| ### Caret, Mark & Tilde | ||
|
|
||
| The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python | ||
| Markdown Extensions][4], allow for the __highlighting of text__, as well as | ||
| __handling sub- and superscripts__: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.caret | ||
| - pymdownx.mark | ||
| - pymdownx.tilde | ||
| ``` | ||
|
|
||
| [6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/ | ||
| [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ | ||
| [8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ | ||
|
|
||
| ### SmartSymbols | ||
|
|
||
| The [SmartSymbols][9] extension, which is also part of [Python Markdown | ||
| Extensions][4], __converts special characters into their corresponding | ||
| symbols__, and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.smartsymbols | ||
| ``` | ||
|
|
||
| See the [official documentation][9] for a list of supported symbols. | ||
|
|
||
| [9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Highlighting changes | ||
|
|
||
| When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the | ||
| ability to _highlight suggested changes_, as well as add _inline comments_ to a | ||
| document: | ||
|
|
||
| [10]: #critic | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| Text can be {--deleted--} and replacement text {++added++}. This can also be | ||
| combined into {~~one~>a single~~} operation. {==Highlighting==} is also | ||
| possible {>>and comments can be added inline<<}. | ||
|
|
||
| {== | ||
|
|
||
| Formatting can also be applied to blocks, by putting the opening and closing | ||
| tags on separate lines and adding new lines between the tags and the content. | ||
|
|
||
| ==} | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| Text can be {--deleted--} and replacement text {++added++}. This can also be | ||
| combined into {~~one~>a single~~} operation. {==Highlighting==} is also | ||
| possible {>>and comments can be added inline<<}. | ||
|
|
||
| {== | ||
|
|
||
| Formatting can also be applied to blocks, by putting the opening and closing | ||
| tags on separate lines and adding new lines between the tags and the content. | ||
|
|
||
| ==} | ||
|
|
||
| ### Highlighting text | ||
|
|
||
| When the [Caret, Mark & Tilde][11] extensions are enabled, text can be | ||
| highlighted with a nicer syntax than using the corresponding `mark`, `ins` and | ||
| `del` HTML tags: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * ==This was marked== | ||
| * ^^This was inserted^^ | ||
| * ~~This was deleted~~ | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * ==This was marked== | ||
| * ^^This was inserted^^ | ||
| * ~~This was deleted~~ | ||
|
|
||
| [11]: #caret-mark-tilde | ||
|
|
||
| ### Sub- and superscripts | ||
|
|
||
| When the [Caret & Tilde][11] extensions are enabled, text can be sub- and | ||
| superscripted with a nicer syntax than using the corresponding `sub` and `sup` | ||
| HTML tags: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * H~2~0 | ||
| * A^T^A | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * H~2~0 | ||
| * A^T^A | ||
|
|
||
| [11]: #caret-mark-tilde |
| @@ -0,0 +1,225 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Icons + Emojis | ||
|
|
||
| One of the best features of Material for MkDocs is the possibility to use [more | ||
| than 7.000 icons][1] and thousands of emojis in your project documentation | ||
| with practically zero additional effort. Furthermore, custom icons can be added | ||
| and used in `mkdocs.yml`, documents and templates. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Emoji | ||
|
|
||
| [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] | ||
|
|
||
| The [Emoji][3] extension, which is part of [Python Markdown Extensions][4], | ||
| adds the ability to __integrate emojis and icons__ in the `*.svg` file format, | ||
| which are inlined when [building your site][5]: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.emoji: | ||
| emoji_index: !!python/name:materialx.emoji.twemoji | ||
| emoji_generator: !!python/name:materialx.emoji.to_svg | ||
| ``` | ||
|
|
||
| The following icon sets are bundled with Material for MkDocs: | ||
|
|
||
| * :material-material-design: – [Material Design][6] | ||
| * :fontawesome-brands-font-awesome-flag: – [FontAwesome][7] | ||
| * :octicons-mark-github-16: – [Octicons][8] | ||
|
|
||
| You can also add [additional icons][9]. When using emojis, it's recommended to | ||
| consult the official documentation of [Python Markdown Extensions][3] to learn | ||
| about configuration options. | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons | ||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss | ||
| [3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ | ||
| [4]: https://facelessuser.github.io/pymdown-extensions/ | ||
| [5]: ../creating-your-site.md#building-your-site | ||
| [6]: https://materialdesignicons.com/ | ||
| [7]: https://fontawesome.com/icons?d=gallery&m=free | ||
| [8]: https://octicons.github.com/ | ||
| [9]: ../setup/changing-the-logo-and-icons.md#additional-icons | ||
|
|
||
| ### Attribute List | ||
|
|
||
| The [Attribute List][10] extension, which is part of the standard Markdown | ||
| library, allows to __add HTML attributes and CSS classes to Markdown elements__, | ||
| and can be enabled via `mkdocs.yml` | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - attr_list | ||
| ``` | ||
|
|
||
| [10]: https://python-markdown.github.io/extensions/attr_list/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using emojis | ||
|
|
||
| Emojis can be integrated in Markdown by putting the shortcode of the emoji | ||
| between two colons. If you're using [Twemoji][11] (recommended), you can look up | ||
| the shortcodes at [Emojipedia][12]. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` | ||
| :smile: | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| :smile: | ||
|
|
||
| [11]: https://twemoji.twitter.com/ | ||
| [12]: https://emojipedia.org/twitter/ | ||
|
|
||
| ### Using icons | ||
|
|
||
| When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing | ||
| a valid path to any icon bundled with the theme, which are located in the | ||
| [`.icons`][1] directory, and replacing `/` with `-`: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` | ||
| * :material-account-circle: – `.icons/material/account-circle.svg` | ||
| * :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg` | ||
| * :octicons-octoface-16: – `.icons/octicons/octoface-16.svg` | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * :material-account-circle: – [`.icons/material/account-circle.svg`][14] | ||
| * :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15] | ||
| * :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16] | ||
|
|
||
| [13]: #emoji | ||
| [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg | ||
| [15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg | ||
| [16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg | ||
|
|
||
| #### with colors | ||
|
|
||
| When the [Attribute List][17] extension is enabled, custom CSS classes and | ||
| attributes can be added to icons by suffixing the icon with a special syntax. | ||
| While HTML and CSS allow to use [inline styles][18], it's always best to add | ||
| an [additional stylesheet][19] and put styles into dedicated CSS classes: | ||
|
|
||
| ``` css | ||
| .medium { | ||
| color: #00AB6C; | ||
| } | ||
| .twitter { | ||
| color: #1DA1F2; | ||
| } | ||
| .facebook { | ||
| color: #4267B2; | ||
| } | ||
| ``` | ||
|
|
||
| Then, simply add the CSS class to the icon. | ||
|
|
||
| <style> | ||
| .medium { | ||
| color: #00AB6C; | ||
| } | ||
| .twitter { | ||
| color: #1DA1F2; | ||
| } | ||
| .facebook { | ||
| color: #4267B2; | ||
| } | ||
| </style> | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * :fontawesome-brands-medium:{: .medium } – Medium | ||
| * :fontawesome-brands-twitter:{: .twitter } – Twitter | ||
| * :fontawesome-brands-facebook:{: .facebook } – Facebook | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * :fontawesome-brands-medium:{: .medium } – Medium | ||
| * :fontawesome-brands-twitter:{: .twitter } – Twitter | ||
| * :fontawesome-brands-facebook:{: .facebook } – Facebook | ||
|
|
||
| [17]: #attribute-list | ||
| [18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style | ||
| [19]: ../customization.md#additional-css | ||
|
|
||
| #### with animations | ||
|
|
||
| Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to | ||
| icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule | ||
| and adding the dedicated CSS class to the icon: | ||
|
|
||
| ``` css | ||
| @keyframes heart { | ||
| 0%, 40%, 80%, 100% { | ||
| transform: scale(1); | ||
| } | ||
| 20%, 60% { | ||
| transform: scale(1.15); | ||
| } | ||
| } | ||
| .heart { | ||
| animation: heart 1000ms infinite; | ||
| } | ||
| ``` | ||
|
|
||
| Then, simply add the CSS class to the icon. | ||
|
|
||
| <style> | ||
| @keyframes heart { | ||
| 0%, 40%, 80%, 100% { | ||
| transform: scale(1); | ||
| } | ||
| 20%, 60% { | ||
| transform: scale(1.15); | ||
| } | ||
| } | ||
| .heart { | ||
| animation: heart 1000ms infinite; | ||
| } | ||
| </style> | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| :octicons-heart-fill-24:{: .heart } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| :octicons-heart-fill-24:{: .heart } | ||
|
|
||
| [20]: #with-colors | ||
| [21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Using icons in templates | ||
|
|
||
| When you're [extending the theme][22] with partials or blocks, you can simply | ||
| reference any icon that's [bundled with the theme][1] with Jinja's | ||
| [`include`][23] function and wrap it with the `twemoji` class: | ||
|
|
||
| ``` html | ||
| <span class="twemoji"> | ||
| {% include ".icons/fontawesome/brands/twitter.svg" %} | ||
| </span> | ||
| ``` | ||
|
|
||
| This is exactly what Material for MkDocs does in its templates. | ||
|
|
||
| [22]: ../customization.md#extending-the-theme | ||
| [23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include |
| @@ -0,0 +1,112 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Images | ||
|
|
||
| While images are first-class citizens of Markdown and part of the core syntax, | ||
| it can be difficult to work with them. Material for MkDocs makes working with | ||
| images more comfortable by providing styles for alignment and image captions. | ||
|
|
||
| [1]: https://www.markdownguide.org/basic-syntax/#images-1 | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Attribute List | ||
|
|
||
| The [Attribute List][2] extension, which is part of the standard Markdown | ||
| library, allows to __add HTML attributes and CSS classes to Markdown elements__, | ||
| and can be enabled via `mkdocs.yml` | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - attr_list | ||
| ``` | ||
|
|
||
| [2]: https://python-markdown.github.io/extensions/attr_list/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Image alignment | ||
|
|
||
| When the [Attribute List][3] extension is enabled, images can be aligned by | ||
| adding the respective alignment directions via the `align` attribute, i.e. | ||
| `align=left` or `align=right` | ||
|
|
||
| === "Left" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| {: align=left } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| {: align=left width=300 } | ||
|
|
||
| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod | ||
| nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor | ||
| massa, nec semper lorem quam in massa. | ||
|
|
||
| === "Right" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| {: align=right } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| {: align=right width=300 } | ||
|
|
||
| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod | ||
| nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor | ||
| massa, nec semper lorem quam in massa. | ||
|
|
||
| _If there's insufficient space to render the text next to the image, the image | ||
| will stretch to the full width of the viewport, e.g. on mobile viewports._ | ||
|
|
||
| [3]: #attribute-list | ||
|
|
||
| ### Image captions | ||
|
|
||
| Sadly, the Markdown syntax doesn't provide native support for image captions, | ||
| but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images. | ||
|
|
||
| _Example_: | ||
|
|
||
| ```html | ||
| <figure> | ||
| <img src="https://dummyimage.com/600x400/eee/aaa" width="300" /> | ||
| <figcaption>Image caption</figcaption> | ||
| </figure> | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| <figure> | ||
| <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" /> | ||
| <figcaption>Image caption</figcaption> | ||
| </figure> | ||
|
|
||
| ### Image lazy-loading | ||
|
|
||
| Modern browsers provide [native support for lazy-loading images][4] through the | ||
| `loading` attribute, which degrades to eager-loading in browsers without | ||
| support. As with [image alignment][5], if the [Attribute List][3] extension is | ||
| enabled, images can be lazy-loaded by adding `loading=lazy`. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| {: loading=lazy } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| {: loading=lazy width=300 } | ||
|
|
||
| [4]: https://caniuse.com/#feat=loading-lazy-attr | ||
| [5]: #image-alignment |
| @@ -0,0 +1,202 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Lists | ||
|
|
||
| Material for MkDocs supports several flavors of lists that cater to different | ||
| use cases, including _unordered lists_ and _ordered lists_, which are supported | ||
| through standard Markdown, as well as _definition lists_ and _task lists_, which | ||
| are supported through extensions. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Definition List | ||
|
|
||
| [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] | ||
|
|
||
| The [Definition List][2] extension, which is part of the standard Markdown | ||
| library, adds the ability to add definitions lists to a document and can be | ||
| enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - def_list | ||
| ``` | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss | ||
| [2]: https://python-markdown.github.io/extensions/definition_lists/ | ||
|
|
||
| ### Tasklist | ||
|
|
||
| [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4] | ||
|
|
||
| The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5], | ||
| adds support for lists with styled checkboxes, and provides several options for | ||
| configuring the style: | ||
|
|
||
| `custom_checkbox`{: #custom-checkbox } | ||
|
|
||
| : :octicons-milestone-24: Default: `false` · This option toggles the rendering | ||
| style of checkboxes, replacing native checkbox styles with beautiful icons, | ||
| and is therefore _strongly recommended_: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.tasklist: | ||
| custom_checkbox: true | ||
| ``` | ||
|
|
||
| `clickable_checkbox`{: #clickable-checkbox } | ||
|
|
||
| : :octicons-milestone-24: Default: `false` · This option toggles whether | ||
| checkboxes are clickable. As the state is not persisted, the use of this | ||
| option is _rather discouraged_ from a user experience perspective: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.tasklist: | ||
| clickable_checkbox: true | ||
| ``` | ||
|
|
||
| [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tasklist.scss | ||
| [4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ | ||
| [5]: https://facelessuser.github.io/pymdown-extensions/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using unordered lists | ||
|
|
||
| An unordered list can be written by prefixing a line with a `-`, `*` or `+` | ||
| list marker, all of which can be used interchangeably. Furthermore, all flavors | ||
| of lists can be nested inside each other. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur | ||
| accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh | ||
| lacinia sed. Aenean in finibus diam. | ||
|
|
||
| * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. | ||
| * Nam vulputate tincidunt fringilla. | ||
| * Nullam dignissim ultrices urna non auctor. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur | ||
| accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh | ||
| lacinia sed. Aenean in finibus diam. | ||
|
|
||
| * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. | ||
| * Nam vulputate tincidunt fringilla. | ||
| * Nullam dignissim ultrices urna non auctor. | ||
|
|
||
| ### Using ordered lists | ||
|
|
||
| An ordered list must start with a number immediately followed by a dot. The | ||
| numbers do not need to be consecutive and can be all set to `1.`, as they will | ||
| be re-numbered when rendered. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| 1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis | ||
| sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis | ||
| nulla. Vivamus a pharetra leo. | ||
|
|
||
| 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet | ||
| quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a | ||
| ultricies libero efficitur sed. | ||
|
|
||
| 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet | ||
| rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. | ||
|
|
||
| 1. Mauris dictum mi lacus | ||
| 2. Ut sit amet placerat ante | ||
| 3. Suspendisse ac eros arcu | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| 1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis | ||
| sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis | ||
| nulla. Vivamus a pharetra leo. | ||
|
|
||
| 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet | ||
| quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a | ||
| ultricies libero efficitur sed. | ||
|
|
||
| 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet | ||
| rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. | ||
|
|
||
| 1. Mauris dictum mi lacus | ||
| 2. Ut sit amet placerat ante | ||
| 3. Suspendisse ac eros arcu | ||
|
|
||
| ### Using definition lists | ||
|
|
||
| [Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g. | ||
| the parameters of functions or modules, as used within this documentation to | ||
| describe extension or plugin parameters. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| `Lorem ipsum dolor sit amet` | ||
| : Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus | ||
| tellus non sem sollicitudin, quis rutrum leo facilisis. | ||
|
|
||
| `Cras arcu libero` | ||
| : Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin | ||
| ut eros sed sapien ullamcorper consequat. Nunc ligula ante. | ||
|
|
||
| Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. | ||
| Nam vulputate tincidunt fringilla. | ||
| Nullam dignissim ultrices urna non auctor. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| `Lorem ipsum dolor sit amet` | ||
| : Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus | ||
| tellus non sem sollicitudin, quis rutrum leo facilisis. | ||
|
|
||
| `Cras arcu libero` | ||
| : Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin | ||
| ut eros sed sapien ullamcorper consequat. Nunc ligula ante. | ||
|
|
||
| Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. | ||
| Nam vulputate tincidunt fringilla. | ||
| Nullam dignissim ultrices urna non auctor. | ||
|
|
||
| [6]: #definition-list | ||
|
|
||
| ### Using tasklists | ||
|
|
||
| When the [Tasklist][7] extension is enabled, unordered list items can be | ||
| prefixed with `[ ]` to render an unchecked or `[x]` to render a checked | ||
| checkbox. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit | ||
| * [ ] Vestibulum convallis sit amet nisi a tincidunt | ||
| * [x] In hac habitasse platea dictumst | ||
| * [x] In scelerisque nibh non dolor mollis congue sed et metus | ||
| * [ ] Praesent sed risus massa | ||
| * [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit | ||
| * [ ] Vestibulum convallis sit amet nisi a tincidunt | ||
| * [x] In hac habitasse platea dictumst | ||
| * [x] In scelerisque nibh non dolor mollis congue sed et metus | ||
| * [ ] Praesent sed risus massa | ||
| * [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque | ||
|
|
||
| [7]: #tasklist |
| @@ -0,0 +1,134 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # MathJax | ||
|
|
||
| [MathJax][1] is a beautiful and accessible way to display _mathematical content_ | ||
| in the browser, allows for writing formulas in different notations, including | ||
| [LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with | ||
| Material for MkDocs. | ||
|
|
||
| [1]: https://www.mathjax.org/ | ||
| [2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics | ||
| [3]: https://en.wikipedia.org/wiki/MathML | ||
| [4]: http://asciimath.org/ | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Arithmatex | ||
|
|
||
| [:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6] | ||
|
|
||
| The [Arithmatex][6] extension, which is part of of [Python Markdown | ||
| Extensions][7], allows the rendering of block and inline block equations, and | ||
| can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.arithmatex: | ||
| generic: true | ||
| ``` | ||
|
|
||
| Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and | ||
| the JavaScript runtime need to be included, which can be done with [additional | ||
| JavaScript][8]: | ||
|
|
||
| === "docs/javascripts/config.js" | ||
|
|
||
| ``` js | ||
| window.MathJax = { | ||
| tex: { | ||
| inlineMath: [["\\(", "\\)"]], | ||
| displayMath: [["\\[", "\\]"]], | ||
| processEscapes: true, | ||
| processEnvironments: true | ||
| }, | ||
| options: { | ||
| ignoreHtmlClass: ".*|", | ||
| processHtmlClass: "arithmatex" | ||
| } | ||
| }; | ||
| ``` | ||
|
|
||
| === "mkdocs.yml" | ||
|
|
||
| ``` yaml | ||
| extra_javascript: | ||
| - javascripts/config.js | ||
| - https://polyfill.io/v3/polyfill.min.js?features=es6 | ||
| - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js | ||
| ``` | ||
|
|
||
| _MathJax can be configured in many different ways, for which Material for MkDocs | ||
| might not provide native support. See the [official documentation][6] for more | ||
| information._ | ||
|
|
||
| !!! tip "Using MathJax with [instant loading][9]" | ||
|
|
||
| There's no additional effort necessary to integrate _MathJax 3_ with | ||
| [instant loading][7] – it's expected to work straight away. However, a | ||
| previous version of this document explained how to integrate Material for | ||
| MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore | ||
| highly recommended to switch to _MathJax 3_. | ||
|
|
||
| <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script> | ||
| <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> | ||
| <script> | ||
| window.MathJax = { | ||
| tex: { | ||
| inlineMath: [["\\(", "\\)"]], | ||
| displayMath: [["\\[", "\\]"]], | ||
| processEscapes: true, | ||
| processEnvironments: true | ||
| }, | ||
| options: { | ||
| ignoreHtmlClass: ".*|", | ||
| processHtmlClass: "arithmatex" | ||
| } | ||
| }; | ||
| </script> | ||
|
|
||
| [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_arithmatex.scss | ||
| [6]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ | ||
| [7]: https://facelessuser.github.io/pymdown-extensions/extensions/ | ||
| [8]: ../customization.md#additional-javascript | ||
| [9]: ../setup/setting-up-navigation.md#instant-loading | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using block syntax | ||
|
|
||
| Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]`on separate lines: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` latex | ||
| $$ | ||
| \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} | ||
| $$ | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| $$ | ||
| \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} | ||
| $$ | ||
|
|
||
| ### Using inline block syntax | ||
|
|
||
| Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` latex | ||
| The homomorphism $f$ is injective if and only if its kernel is only the | ||
| singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such | ||
| that $f(a)=f(b)$. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| The homomorphism $f$ is injective if and only if its kernel is only the | ||
| singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such | ||
| that $f(a)=f(b)$. |
| @@ -0,0 +1,136 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Meta tags | ||
|
|
||
| In HTML, `meta` tags allow to provide additional metadata for a document, e.g. | ||
| page titles and descriptions, additional assets to be loaded, and [Open Graph] | ||
| [1] data. While metadata can always be added via [customization][2], some tags | ||
| can be configured. | ||
|
|
||
| [1]: https://ogp.me/ | ||
| [2]: #customization | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Metadata | ||
|
|
||
| The [Metadata][3] extension, which is part of the standard Markdown library, | ||
| adds the ability to add [front matter][4] to a document and can be enabled via | ||
| `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - meta | ||
| ``` | ||
|
|
||
| Front matter is written as a series of key-value pairs at the beginning of the | ||
| Markdown document, delimited by a blank line which ends the YAML context. | ||
|
|
||
| [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html | ||
| [4]: https://jekyllrb.com/docs/front-matter/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Setting the page title | ||
|
|
||
| If the [Metadata][5] extension is enabled, the page title can be overridden on | ||
| a per-document basis with custom front matter: | ||
|
|
||
| ``` markdown | ||
| --- | ||
| title: Lorem ipsum dolor sit amet | ||
| --- | ||
| ``` | ||
|
|
||
| This will set the `title` tag inside the document `head` for the current page | ||
| to the provided value. Note that the site title is appended using a dash as a | ||
| separator, which is the default behavior. | ||
|
|
||
| [5]: #metadata | ||
|
|
||
| ### Setting the page description | ||
|
|
||
| If the [Metadata][5] extension is enabled, the page description can also be | ||
| overridden on a per-document basis with custom front matter: | ||
|
|
||
| ``` markdown | ||
| --- | ||
| description: Nullam urna elit, malesuada eget finibus ut, ac tortor. | ||
| --- | ||
| ``` | ||
|
|
||
| This will set the `meta` tag containing the site description inside the | ||
| document `head` for the current page to the provided value. | ||
|
|
||
| ### Adding a web app manifest | ||
|
|
||
| A [web app manifest][6] is a simple JSON file that specifies how your web application should behave when installed on the user's mobile device or desktop, which can be set via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| manifest: manifest.webmanifest | ||
| ``` | ||
|
|
||
| [6]: https://developers.google.com/web/fundamentals/web-app-manifest/ | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom meta tags | ||
|
|
||
| In order to add `meta` tags to your document, you can [extend the theme][7] and | ||
| simply [override the `extrahead` block][8] with the respective tags, e.g. to set | ||
| policies for search engines: | ||
|
|
||
| ``` html | ||
| {% block extrahead %} | ||
| <meta property="robots" content="noindex, nofollow" /> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| Some further examples, including [Open Graph][1] and [Twitter Cards][9]: | ||
|
|
||
| === "Open Graph" | ||
|
|
||
| ``` html | ||
| {% block extrahead %} | ||
| {% set title = config.site_name %} | ||
| {% 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 %} | ||
| {% endif %} | ||
| <meta property="og:type" content="website" /> | ||
| <meta property="og:title" content="{{ title }}" /> | ||
| <meta property="og:description" content="{{ config.site_description }}" /> | ||
| <meta property="og:url" content="{{ page.canonical_url }}" /> | ||
| <meta property="og:image" content="<url>" /> | ||
| <meta property="og:image:type" content="image/png" /> | ||
| <meta property="og:image:width" content="1200" /> | ||
| <meta property="og:image:height" content="630" /> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| === "Twitter Cards" | ||
|
|
||
| ``` html | ||
| {% block extrahead %} | ||
| {% set title = config.site_name %} | ||
| {% 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 %} | ||
| {% endif %} | ||
| <meta name="twitter:card" content="summary_large_image" /> | ||
| <meta name="twitter:site" content="<username>" /> | ||
| <meta name="twitter:creator" content="<username>" /> | ||
| <meta name="twitter:title" content="{{ title }}" /> | ||
| <meta name="twitter:description" content="{{ config.site_description }}" /> | ||
| <meta name="twitter:image" content="<url>" /> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| [7]: ../customization.md#extending-the-theme | ||
| [8]: ../customization.md#overriding-blocks | ||
| [9]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards |
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Variables | ||
|
|
||
| Macros and variables are powerful tools to parametrize Markdown files, as they | ||
| allow to perform Jinja templating directly from Markdown. This is especially | ||
| useful to include technical data from other files and add central variables via | ||
| `mkdocs.yml`. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Macros | ||
|
|
||
| The [macros][1] plugin adds support to reference variables and call macros and | ||
| supports Jinja templating directly from Markdown. It can be installed with | ||
| `pip`: | ||
|
|
||
| ``` | ||
| pip install mkdocs-macros-plugin | ||
| ``` | ||
|
|
||
| Then, add the following to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - macros | ||
| ``` | ||
|
|
||
| [1]: https://github.com/fralau/mkdocs_macros_plugin | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using predefined variables | ||
|
|
||
| A set of predefined variables is enabled by default and can be used from | ||
| Markdown, including data from `mkdocs.yml`. More specifically, predefined | ||
| variables fall into the following categories: | ||
|
|
||
| - `config.*`: configuration parameters from `mkdocs.yml` | ||
| - `page.*`: metadata and content of current page | ||
| - `navigation.*`: list of all pages and sections | ||
| - `environment.*`: underlying operating system | ||
| - `git.*`: git-related information, if available | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| Welcome to {{ config.site_name }}! | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| ``` markdown | ||
| Welcome to Material for MkDocs! | ||
| ``` | ||
|
|
||
| A list of all predefined variables can be printed with: | ||
|
|
||
| ``` | ||
| {{ macros_info() }} | ||
| ``` | ||
|
|
||
| ### Using custom variables | ||
|
|
||
| All data defined under `extra` in `mkdocs.yml` is automatically exposed as a | ||
| variable and can be used from the template. This enables centralized parameter | ||
| storage and management. | ||
|
|
||
| _Example_: | ||
|
|
||
| === "docs/page.md" | ||
|
|
||
| ```` markdown | ||
| The unit price is {{ unit.price }} | ||
| ```` | ||
|
|
||
| === "mkdocs.yml" | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| unit: | ||
| price: 12.50 | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| The unit price is 12.50. | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom macros | ||
|
|
||
| The [macros][1] plugin allows to define custom macros, which can then be used | ||
| from Markdown files. See the [official documentation][2] for more information | ||
| how to define custom macros. | ||
|
|
||
| [2]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/ |
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Adding a comment system | ||
|
|
||
| Material for MkDocs is natively integrated with [Disqus][1], a comment system | ||
| that provides a wide range of features like social integrations, user profiles, | ||
| as well as spam and moderation tools. Of course, other comment systems can be | ||
| integrated, too. | ||
|
|
||
| [1]: https://disqus.com/ | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Disqus | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-milestone-24: Default: _none_ | ||
|
|
||
| First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate | ||
| Material for MkDocs with [Disqus][1], create an account and a site giving you a | ||
| [shortname][4], and add it to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| disqus: <shortname> | ||
| ``` | ||
|
|
||
| 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 | ||
| [3]: https://www.mkdocs.org/user-guide/configuration/#site_url | ||
| [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname | ||
|
|
||
| ### Metadata | ||
|
|
||
| The [Metadata][5] extension, which is part of the standard Markdown library, | ||
| adds the ability to add [front matter][6] to a document and can be enabled via | ||
| `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - meta | ||
| ``` | ||
|
|
||
| Front matter is written as a series of key-value pairs at the beginning of the | ||
| Markdown document, delimited by a blank line which ends the YAML context. | ||
|
|
||
| [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html | ||
| [6]: https://jekyllrb.com/docs/front-matter/ | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Selective integration | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| If the [Metadata][7] extension is enabled, you can disable or enable Disqus for | ||
| specific pages by adding the following to the front matter of a page: | ||
|
|
||
| === "Enable Disqus" | ||
|
|
||
| ``` markdown | ||
| --- | ||
| disqus: <shortname> | ||
| --- | ||
| ``` | ||
|
|
||
| === "Disable Disqus" | ||
|
|
||
| ``` markdown | ||
| --- | ||
| disqus: "" | ||
| --- | ||
| ``` | ||
|
|
||
| [7]: #metadata | ||
|
|
||
| ### Other comment systems | ||
|
|
||
| [:octicons-file-code-24: Source][8] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| In order to integrate another JavaScript-based comment system provider, you can | ||
| [extend the theme][9] and [override the `disqus` block][10]: | ||
|
|
||
| ``` html | ||
| {% block disqus %} | ||
| <!-- Add custom comment system integration here --> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L343-L345 | ||
| [9]: ../customization.md#extending-the-theme | ||
| [10]: ../customization.md#overriding-blocks |
| @@ -0,0 +1,193 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Adding a git repository | ||
|
|
||
| If your documentation is related to source code, Material for MkDocs provides | ||
| the ability to display information to the project's repository as part of the | ||
| static site, including statistics like stars and forks. Furthermore, individual | ||
| documents can be linked to specific source files. | ||
|
|
||
| ## Configuration | ||
|
|
||
| In order to display a link to the repository of your project as part of your | ||
| documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your | ||
| repository, e.g.: | ||
|
|
||
| ``` yaml | ||
| repo_url: https://github.com/squidfunk/mkdocs-material | ||
| ``` | ||
|
|
||
| The link to the repository will be rendered next to the search bar on big | ||
| screens and as part of the main navigation drawer on smaller screen sizes. | ||
| Additionally, for GitHub and GitLab, the number of stars and forks is | ||
| automatically requested and rendered for _public repositories_. | ||
|
|
||
| [1]: https://www.mkdocs.org/user-guide/configuration/#repo_url | ||
|
|
||
| ### Repository name | ||
|
|
||
| [:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default: | ||
| _automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` | ||
|
|
||
| MkDocs will infer the source provider by examining the URL and try to set the | ||
| _repository name_ automatically. If you wish to customize the name, set | ||
| [`repo_name`][3] in `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| repo_name: squidfunk/mkdocs-material | ||
| ``` | ||
|
|
||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html | ||
| [3]: https://www.mkdocs.org/user-guide/configuration/#repo_name | ||
|
|
||
| ### Repository icon | ||
|
|
||
| [:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default: | ||
| `fontawesome/brands/git-alt` | ||
|
|
||
| While the default _repository icon_ is a generic git icon, it can be set to | ||
| [any icon bundled with the theme][4] by referencing a valid icon path in | ||
| `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| icon: | ||
| repo: fontawesome/brands/git-alt | ||
| ``` | ||
|
|
||
| Some popular choices: | ||
|
|
||
| * :fontawesome-brands-git: – `fontawesome/brands/git` | ||
| * :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt` | ||
| * :fontawesome-brands-git-square: – `fontawesome/brands/git-square` | ||
| * :fontawesome-brands-github: – `fontawesome/brands/github` | ||
| * :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt` | ||
| * :fontawesome-brands-github-square: – `fontawesome/brands/github-square` | ||
| * :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab` | ||
| * :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken` | ||
| * :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket` | ||
| * :fontawesome-solid-trash: – `fontawesome/solid/trash` | ||
|
|
||
| [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons | ||
|
|
||
| ### Edit button | ||
|
|
||
| [:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: | ||
| _automatically set_ | ||
|
|
||
| If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8] | ||
| repository, an _edit button_ is displayed at the top of each document. This | ||
| behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`: | ||
|
|
||
| === "Customize edit path" | ||
|
|
||
| ``` yaml | ||
| edit_uri: edit/master/docs/ | ||
| ``` | ||
|
|
||
| === "Hide edit button" | ||
|
|
||
| ``` yaml | ||
| edit_uri: "" | ||
| ``` | ||
|
|
||
| [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L302-L311 | ||
| [6]: https://github.com/ | ||
| [7]: https://about.gitlab.com/ | ||
| [8]: https://bitbucket.org/ | ||
| [9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri | ||
|
|
||
| ### Revision date | ||
|
|
||
| [:octicons-file-code-24: Source][10] · | ||
| [:octicons-cpu-24: Plugin][11] | ||
|
|
||
| The [git-revision-date][11] plugin adds support for displaying the date a | ||
| document was _last updated_ at the bottom of each page. It can be installed | ||
| with `pip`: | ||
|
|
||
| ``` | ||
| pip install mkdocs-git-revision-date-plugin | ||
| ``` | ||
|
|
||
| Then, add the following to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - git-revision-date | ||
| ``` | ||
|
|
||
| The following options are supported: | ||
|
|
||
| `enabled_if_env`{: #enabled_if_env } | ||
|
|
||
| : :octicons-milestone-24: Default: _none_ – This option defines whether the | ||
| date is actually extracted from git, which makes it possible to disable | ||
| extraction for cases when the repository is not available: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - git-revision-date: | ||
| enabled_if_env: CI | ||
| ``` | ||
|
|
||
| _Material for MkDocs doesn't provide official support for the other options of | ||
| this plugin, so they may be supported but can also yield weird results. Use | ||
| them at your own risk._ | ||
|
|
||
| [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html | ||
| [11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin | ||
|
|
||
| ### Revision date, localized | ||
|
|
||
| [:octicons-file-code-24: Source][10] · | ||
| [:octicons-cpu-24: Plugin][12] | ||
|
|
||
| Similarly, the [git-revision-date-localized][12] plugin adds support for adding | ||
| a localized _last updated_ date at the bottom of each page. It can be installed | ||
| with `pip`: | ||
|
|
||
| ``` | ||
| pip install mkdocs-git-revision-date-localized-plugin | ||
| ``` | ||
|
|
||
| Then, add the following to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - git-revision-date-localized | ||
| ``` | ||
|
|
||
| The following options are supported: | ||
|
|
||
| `type`{: #type } | ||
|
|
||
| : :octicons-milestone-24: Default: `date` – This option allows to change the | ||
| format of the date to be displayed. Valid values are `date`, `datetime`, | ||
| `iso_date`, `iso_datetime` and `timeago`: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - git-revision-date-localized: | ||
| type: date | ||
| ``` | ||
|
|
||
| `fallback_to_build_date`{: #fallback_to_build_date } | ||
|
|
||
| : :octicons-milestone-24: Default: `false` – This option specifies whether | ||
| the time when `mkdocs build` was executed should be used as a fallback when | ||
| the git repository is not available: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - git-revision-date-localized: | ||
| fallback_to_build_date: true | ||
| ``` | ||
|
|
||
| _Material for MkDocs doesn't provide official support for the other options of | ||
| this plugin, so they may be supported but can also yield weird results. Use | ||
| them at your own risk._ | ||
|
|
||
| [12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin |
| @@ -0,0 +1,104 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Adding social links | ||
|
|
||
| The footer of your project documentation is a great place to add links to | ||
| websites or platforms you or your company are using as additional marketing | ||
| channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" }, | ||
| :fontawesome-brands-twitter:{: style="color: #1DA1F2" } or | ||
| :fontawesome-brands-facebook:{: style="color: #4267B2" }, which can be | ||
| configured via `mkdocs.yml`. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Social links | ||
|
|
||
| [:octicons-file-code-24: Source][1] · | ||
| :octicons-milestone-24: Default: _none_ | ||
|
|
||
| All _social links_ are rendered next to the copyright information as part of the | ||
| footer of your project documentation. Add a list of social links in `mkdocs.yml` | ||
| with: | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| social: | ||
| - icon: fontawesome/brands/twitter | ||
| link: https://twitter.com/squidfunk | ||
| ``` | ||
|
|
||
| For each entry, the following fields are available: | ||
|
|
||
| `icon`{: #icon } | ||
|
|
||
| : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – | ||
| 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: | ||
|
|
||
| * :fontawesome-brands-behance: – `fontawesome/brands/behance` | ||
| * :fontawesome-brands-docker: – `fontawesome/brands/docker` | ||
| * :fontawesome-brands-github: – `fontawesome/brands/github` | ||
| * :fontawesome-brands-instagram: – `fontawesome/brands/instagram` | ||
| * :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin` | ||
| * :fontawesome-brands-medium: – `fontawesome/brands/medium` | ||
| * :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt` | ||
| * :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt` | ||
| * :fontawesome-brands-slack: – `fontawesome/brands/slack` | ||
| * :fontawesome-brands-twitter: – `fontawesome/brands/twitter` | ||
|
|
||
| [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 } | ||
|
|
||
| : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – | ||
| This field must contain a valid relative or absolute URL including the URI | ||
| scheme. All URI schemes are supported, including `mailto` and `bitcoin`: | ||
|
|
||
| === "Twitter" | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| social: | ||
| - icon: fontawesome/brands/twitter | ||
| link: https://twitter.com/squidfunk | ||
| ``` | ||
|
|
||
| === "Email address" | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| social: | ||
| - icon: fontawesome/solid/paper-plane | ||
| link: mailto:<email-address> | ||
| ``` | ||
|
|
||
| `name`{: #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 | ||
| discernable name to improve accessibility: | ||
|
|
||
| ``` yaml | ||
| extra: | ||
| social: | ||
| - icon: fontawesome/brands/twitter | ||
| link: https://twitter.com/squidfunk | ||
| name: squidfunk on Twitter | ||
| ``` | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom icons | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-mortar-board-24: Difficulty: _moderate_ | ||
|
|
||
| The social links feature uses the standard [icon integration][3] of Material for | ||
| MkDocs. If you want to use custom icons, follow the guide explaining how to | ||
| add [additional icons][4]. | ||
|
|
||
| [3]: changing-the-logo-and-icons.md#icons | ||
| [4]: changing-the-logo-and-icons.md#additional-icons |
| @@ -0,0 +1,306 @@ | ||
| --- | ||
| 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 | ||
| `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to | ||
| fit your brand's identity by using [CSS variables][2]. | ||
|
|
||
| [1]: http://www.materialui.co/colors | ||
| [2]: #custom-colors | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Color palette | ||
|
|
||
| #### Color scheme | ||
|
|
||
| [:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default` | ||
|
|
||
| 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`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| palette: | ||
| scheme: default | ||
| ``` | ||
|
|
||
| :material-cursor-default-click-outline: Click on a tile to change the color | ||
| scheme: | ||
|
|
||
| <div class="tx-switch"> | ||
| <button data-md-color-scheme="default"><code>default</code></button> | ||
| <button data-md-color-scheme="slate"><code>slate</code></button> | ||
| </div> | ||
|
|
||
| <script> | ||
| var buttons = document.querySelectorAll("button[data-md-color-scheme]") | ||
| buttons.forEach(function(button) { | ||
| button.addEventListener("click", function() { | ||
| var attr = this.getAttribute("data-md-color-scheme") | ||
| document.body.setAttribute("data-md-color-scheme", attr) | ||
| var name = document.querySelector("#__code_0 code span:nth-child(7)") | ||
| name.textContent = attr | ||
| }) | ||
| }) | ||
| </script> | ||
|
|
||
| The _color scheme_ can also be set based on _user preference_, which makes use | ||
| of the `prefers-color-scheme` media query, by setting the value in `mkdocs.yml` | ||
| to `preference`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| palette: | ||
| scheme: preference | ||
| ``` | ||
|
|
||
| [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss | ||
|
|
||
| #### Primary color | ||
|
|
||
| [:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo` | ||
|
|
||
| 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: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| palette: | ||
| primary: indigo | ||
| ``` | ||
|
|
||
| :material-cursor-default-click-outline: Click on a tile to change the primary | ||
| color: | ||
|
|
||
| <div class="tx-switch"> | ||
| <button data-md-color-primary="red"><code>red</code></button> | ||
| <button data-md-color-primary="pink"><code>pink</code></button> | ||
| <button data-md-color-primary="purple"><code>purple</code></button> | ||
| <button data-md-color-primary="deep-purple"><code>deep purple</code></button> | ||
| <button data-md-color-primary="indigo"><code>indigo</code></button> | ||
| <button data-md-color-primary="blue"><code>blue</code></button> | ||
| <button data-md-color-primary="light-blue"><code>light blue</code></button> | ||
| <button data-md-color-primary="cyan"><code>cyan</code></button> | ||
| <button data-md-color-primary="teal"><code>teal</code></button> | ||
| <button data-md-color-primary="green"><code>green</code></button> | ||
| <button data-md-color-primary="light-green"><code>light green</code></button> | ||
| <button data-md-color-primary="lime"><code>lime</code></button> | ||
| <button data-md-color-primary="yellow"><code>yellow</code></button> | ||
| <button data-md-color-primary="amber"><code>amber</code></button> | ||
| <button data-md-color-primary="orange"><code>orange</code></button> | ||
| <button data-md-color-primary="deep-orange"><code>deep orange</code></button> | ||
| <button data-md-color-primary="brown"><code>brown</code></button> | ||
| <button data-md-color-primary="grey"><code>grey</code></button> | ||
| <button data-md-color-primary="blue-grey"><code>blue grey</code></button> | ||
| <button data-md-color-primary="black"><code>black</code></button> | ||
| <button data-md-color-primary="white"><code>white</code></button> | ||
| </div> | ||
|
|
||
| <script> | ||
| var buttons = document.querySelectorAll("button[data-md-color-primary]") | ||
| buttons.forEach(function(button) { | ||
| button.addEventListener("click", function() { | ||
| var attr = this.getAttribute("data-md-color-primary") | ||
| document.body.setAttribute("data-md-color-primary", attr) | ||
| var name = document.querySelector("#__code_2 code span:nth-child(7)") | ||
| name.textContent = attr.replace("-", " ") | ||
| }) | ||
| }) | ||
| </script> | ||
|
|
||
| [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss | ||
|
|
||
| #### Accent color | ||
|
|
||
| [:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo` | ||
|
|
||
| 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: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| palette: | ||
| accent: indigo | ||
| ``` | ||
|
|
||
| :material-cursor-default-click-outline: Click on a tile to change the accent | ||
| color: | ||
|
|
||
| <style> | ||
| .md-typeset button[data-md-color-accent] > code { | ||
| background-color: var(--md-code-bg-color); | ||
| color: var(--md-accent-fg-color); | ||
| } | ||
| </style> | ||
|
|
||
| <div class="tx-switch"> | ||
| <button data-md-color-accent="red"><code>red</code></button> | ||
| <button data-md-color-accent="pink"><code>pink</code></button> | ||
| <button data-md-color-accent="purple"><code>purple</code></button> | ||
| <button data-md-color-accent="deep-purple"><code>deep purple</code></button> | ||
| <button data-md-color-accent="indigo"><code>indigo</code></button> | ||
| <button data-md-color-accent="blue"><code>blue</code></button> | ||
| <button data-md-color-accent="light-blue"><code>light blue</code></button> | ||
| <button data-md-color-accent="cyan"><code>cyan</code></button> | ||
| <button data-md-color-accent="teal"><code>teal</code></button> | ||
| <button data-md-color-accent="green"><code>green</code></button> | ||
| <button data-md-color-accent="light-green"><code>light green</code></button> | ||
| <button data-md-color-accent="lime"><code>lime</code></button> | ||
| <button data-md-color-accent="yellow"><code>yellow</code></button> | ||
| <button data-md-color-accent="amber"><code>amber</code></button> | ||
| <button data-md-color-accent="orange"><code>orange</code></button> | ||
| <button data-md-color-accent="deep-orange"><code>deep orange</code></button> | ||
| </div> | ||
|
|
||
| <script> | ||
| var buttons = document.querySelectorAll("button[data-md-color-accent]") | ||
| buttons.forEach(function(button) { | ||
| button.addEventListener("click", function() { | ||
| var attr = this.getAttribute("data-md-color-accent") | ||
| document.body.setAttribute("data-md-color-accent", attr) | ||
| var name = document.querySelector("#__code_3 code span:nth-child(7)") | ||
| name.textContent = attr.replace("-", " ") | ||
| }) | ||
| }) | ||
| </script> | ||
|
|
||
| [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss | ||
|
|
||
| --- | ||
|
|
||
| !!! warning "Accessibility – not all color combinations work well" | ||
|
|
||
| With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color) | ||
| = __714__ combinations, it's impossible to ensure that all configurations | ||
| provide a good user experience (e.g. _yellow on light background_). Make | ||
| sure that the color combination of your choosing provides enough contrast | ||
| and tweak CSS variables where necessary. | ||
|
|
||
| ### Color palette toggle | ||
|
|
||
| [:octicons-file-code-24: Source][6] · | ||
| :octicons-beaker-24: Experimental · | ||
| [:octicons-heart-fill-24:{: .tx-heart } Insiders only][6]{: .tx-insiders } | ||
|
|
||
| [Material for MkDocs Insiders][6] makes it possible to define multiple color | ||
| palettes, including a [scheme][7], [primary][8] and [accent][9] color each, and | ||
| let the user choose. Define them via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| palette: | ||
| - scheme: default | ||
| primary: indigo | ||
| accent: indigo | ||
| toggle: | ||
| icon: material/toggle-switch | ||
| name: Switch to light mode | ||
| - scheme: slate | ||
| primary: blue | ||
| accent: blue | ||
| toggle: | ||
| icon: material/toggle-switch-off-outline | ||
| name: Switch to dark mode | ||
| ``` | ||
|
|
||
| The `toggle` field allows to specify an `icon` and `name` for each palette. The | ||
| toggle is rendered next to the search bar and will cycle through all defined | ||
| color palettes: | ||
|
|
||
| `icon`{: #icon } | ||
|
|
||
| : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – | ||
| This field must point to a valid icon path referencing [any icon bundled | ||
| with the theme][10], or the build will not succeed. Some popular | ||
| combinations: | ||
|
|
||
| * :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch` | ||
| * :material-weather-sunny: + :material-weather-night: – `material/weather-sunny` + `material/weather-night` | ||
| * :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye` | ||
| * :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb` | ||
|
|
||
| `name`{: #name } | ||
|
|
||
| : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – | ||
| This field is used as the toggle's `title` attribute and should be set to a | ||
| discernable name to improve accessibility. | ||
|
|
||
| _Give this feature a try on [the official documentation][11] built with Material | ||
| for MkDocs Insiders!_ | ||
|
|
||
| [6]: ../insiders.md | ||
| [7]: #color-scheme | ||
| [8]: #primary-color | ||
| [9]: #accent-color | ||
| [10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons | ||
| [11]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom colors | ||
|
|
||
| [:octicons-file-code-24: Source][12] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| Material for MkDocs implements colors using [CSS variables][13] (custom | ||
| properties). If you want to customize the colors beyond the palette (e.g. to | ||
| use your brand-specific colors), you can add an [additional stylesheet][14] and | ||
| tweak the values of the CSS variables. | ||
|
|
||
| Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" } | ||
| __YouTube__, and want to set the primary color to your brand's palette. Just | ||
| add: | ||
|
|
||
| ``` css | ||
| :root { | ||
| --md-primary-fg-color: #EE0F0F; | ||
| --md-primary-fg-color--light: #ECB7B7; | ||
| --md-primary-fg-color--dark: #90030C; | ||
| } | ||
| ``` | ||
|
|
||
| See the file containing the [color definitions][12] for a list of all CSS | ||
| variables. | ||
|
|
||
| [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss | ||
| [13]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties | ||
| [14]: ../customization.md#additional-css | ||
|
|
||
|
|
||
| ### Custom color schemes | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| Besides overriding specific colors, you can create your own, named color scheme | ||
| by wrapping the definitions in the `#!css [data-md-color-scheme="..."]` | ||
| [attribute selector][15], which you can then set via `mkdocs.yml` as described | ||
| in the [color schemes][7] section: | ||
|
|
||
| ``` css | ||
| [data-md-color-scheme="youtube"] { | ||
| --md-primary-fg-color: #EE0F0F; | ||
| --md-primary-fg-color--light: #ECB7B7; | ||
| --md-primary-fg-color--dark: #90030C; | ||
| } | ||
| ``` | ||
|
|
||
| Additionally, the `slate` color scheme defines all of it's colors via `hsla` | ||
| color functions and deduces its colors from the `--md-hue` CSS variable. You | ||
| can tune the `slate` theme with: | ||
|
|
||
| ``` css | ||
| [data-md-color-scheme="slate"] { | ||
| --md-hue: 210; /* [0, 360] */ | ||
| } | ||
| ``` | ||
|
|
||
| [15]: https://www.w3.org/TR/selectors-4/#attribute-selectors |
| @@ -0,0 +1,112 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Changing the fonts | ||
|
|
||
| Material for MkDocs makes it easy to change the typeface of your project | ||
| documentation, as it directly integrates with [Google Fonts][1]. Alternatively, | ||
| fonts can be custom-loaded if self-hosting is preferred for data privacy reasons | ||
| or another destination should be used. | ||
|
|
||
| [1]: https://fonts.google.com | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Regular font | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-milestone-24: Default: [`Roboto`][3] | ||
|
|
||
| The _regular font_ is used for all body copy, headlines, and essentially | ||
| everything that does not need to be proportionally spaced. It can be set to any | ||
| valid [Google Font][1] with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| font: | ||
| text: Roboto | ||
| ``` | ||
|
|
||
| The typeface will be loaded in 300, 400, _400i_ and __700__. | ||
|
|
||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L119-L143 | ||
| [3]: https://fonts.google.com/specimen/Roboto | ||
|
|
||
| ### Proportional font | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-milestone-24: Default: [`Roboto Mono`][4] | ||
|
|
||
| The _proportional font_ is used for code blocks and can be configured separately. | ||
| Just like the regular font, it can be set to any valid [Google Font][1] via | ||
| `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| font: | ||
| code: Roboto Mono | ||
| ``` | ||
|
|
||
| The typeface will be loaded in 400. | ||
|
|
||
| [4]: https://fonts.google.com/specimen/Roboto+Mono | ||
|
|
||
| ## Customization | ||
|
|
||
| If you want to load fonts from other destinations or don't want to use Google | ||
| Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize | ||
| font loading as described below. | ||
|
|
||
| ### Disabling font loading | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| If you want to prevent typefaces from being loaded from Google Fonts and fall | ||
| back to system fonts, add the following lines to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| font: false | ||
| ``` | ||
|
|
||
| ### Additional fonts | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| If you want to load an (additional) font from another or override | ||
| the fallback font, you can use an [additional stylesheet][8] to add the | ||
| corresponding `@font-face` definition: | ||
|
|
||
| ``` css | ||
| @font-face { | ||
| font-family: "<font>"; | ||
| src: "..."; | ||
| } | ||
| ``` | ||
|
|
||
| The font can then be applied to specific elements, e.g. only headlines, or | ||
| globally to be used as the site-wide regular or proportional font: | ||
|
|
||
| === "Regular font" | ||
|
|
||
| ``` css | ||
| body, input { | ||
| font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif; | ||
| } | ||
| ``` | ||
|
|
||
| === "Proportional font" | ||
|
|
||
| ``` css | ||
| pre, code, kbd { | ||
| font-family: "<font>", SFMono-Regular, Consolas, Menlo, monospace; | ||
| } | ||
| ``` | ||
|
|
||
| [5]: ../data-privacy.md | ||
| [6]: ../customization.md#extending-the-theme | ||
| [7]: ../customization.md#overriding-blocks | ||
| [8]: ../customization.md#additional-stylesheets |
| @@ -0,0 +1,163 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Changing the language | ||
|
|
||
| Material for MkDocs supports internationalization (i18n) and provides | ||
| translations for template variables and labels in 40+ languages. Additionally, | ||
| the site search can be configured to use a language-specific stemmer (if | ||
| available). | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Site language | ||
|
|
||
| [:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en` | ||
|
|
||
| You can set the _site language_ in `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| language: en | ||
| ``` | ||
|
|
||
| The following languages are supported: | ||
|
|
||
| <ul class="tx-columns"> | ||
| <li><code>af</code> – Afrikaans</li> | ||
| <li><code>ar</code> – Arabic</li> | ||
| <li><code>bn</code> – Bengali (Bangla)</li> | ||
| <li><code>ca</code> – Catalan</li> | ||
| <li><code>cs</code> – Czech</li> | ||
| <li><code>da</code> – Danish</li> | ||
| <li><code>de</code> – German</li> | ||
| <li><code>en</code> – English</li> | ||
| <li><code>eo</code> – Esperanto</li> | ||
| <li><code>es</code> – Spanish</li> | ||
| <li><code>et</code> – Estonian</li> | ||
| <li><code>fa</code> – Persian (Farsi)</li> | ||
| <li><code>fi</code> – Finnish</li> | ||
| <li><code>fr</code> – French</li> | ||
| <li><code>gl</code> – Galician</li> | ||
| <li><code>gr</code> – Greek</li> | ||
| <li><code>he</code> – Hebrew</li> | ||
| <li><code>hi</code> – Hindi</li> | ||
| <li><code>hr</code> – Croatian</li> | ||
| <li><code>hu</code> – Hungarian</li> | ||
| <li><code>id</code> – Indonesian</li> | ||
| <li><code>it</code> – Italian</li> | ||
| <li><code>ja</code> – Japanese</li> | ||
| <li><code>kr</code> – Korean</li> | ||
| <li><code>my</code> – Burmese</li> | ||
| <li><code>nl</code> – Dutch</li> | ||
| <li><code>nn</code> – Norwegian (Nynorsk)</li> | ||
| <li><code>no</code> – Norwegian</li> | ||
| <li><code>pl</code> – Polish</li> | ||
| <li><code>pt</code> – Portuguese</li> | ||
| <li><code>ro</code> – Romanian</li> | ||
| <li><code>ru</code> – Russian</li> | ||
| <li><code>sh</code> – Serbo-Croatian</li> | ||
| <li><code>si</code> – Slovenian</li> | ||
| <li><code>sk</code> – Slovak</li> | ||
| <li><code>sr</code> – Serbian</li> | ||
| <li><code>sv</code> – Swedish</li> | ||
| <li><code>th</code> – Thai</li> | ||
| <li><code>tr</code> – Turkish</li> | ||
| <li><code>uk</code> – Ukrainian</li> | ||
| <li><code>vi</code> – Vietnamese</li> | ||
| <li><code>zh</code> – Chinese (Simplified)</li> | ||
| <li><code>zh-Hant</code> – Chinese (Traditional)</li> | ||
| <li><code>zh-TW</code> – Chinese (Taiwanese)</li> | ||
| <li> | ||
| <a href="https://bit.ly/38F5RCa"> | ||
| Add language | ||
| </a> | ||
| </li> | ||
| </ul> | ||
|
|
||
| _Note that some languages will produce unreadable anchor links, due to the way | ||
| the default slug function works. Consider using a Unicode-aware slug function, | ||
| as [documented here][2]._ | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html | ||
| [2]: setting-up-navigation.md#slugify | ||
|
|
||
| ### Site search language | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-milestone-24: Default: _automatically set_ | ||
|
|
||
| Some languages, like Arabic or Japanese, need dedicated stemmers for search to | ||
| work properly. Material for MkDocs relies on [lunr-languages][4] to provide this | ||
| functionality. See the guide detailing how to [set up site search][5] for | ||
| more information. | ||
|
|
||
| [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69 | ||
| [4]: https://github.com/MihaiValentin/lunr-languages | ||
| [5]: setting-up-site-search.md | ||
|
|
||
| ### Directionality | ||
|
|
||
| [:octicons-file-code-24: Source][6] · | ||
| :octicons-milestone-24: Default: _automatically set_ | ||
|
|
||
| While many languages are read `ltr` (left-to-right), Material for MkDocs also | ||
| supports `rtl` (right-to-left) _directionality_ which is inferred from the | ||
| selected language, but can also be set with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| direction: ltr | ||
| ``` | ||
|
|
||
| :material-cursor-default-click-outline: Click on a tile to change the | ||
| directionality: | ||
|
|
||
| <div class="tx-switch"> | ||
| <button data-md-dir="ltr"><code>ltr</code></button> | ||
| <button data-md-dir="rtl"><code>rtl</code></button> | ||
| </div> | ||
|
|
||
| <script> | ||
| var buttons = document.querySelectorAll("button[data-md-dir]") | ||
| buttons.forEach(function(button) { | ||
| button.addEventListener("click", function() { | ||
| var attr = this.getAttribute("data-md-dir") | ||
| document.body.dir = attr | ||
| var name = document.querySelector("#__code_1 code span:nth-child(5)") | ||
| name.textContent = attr | ||
| }) | ||
| }) | ||
| </script> | ||
|
|
||
| [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L171 | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom translations | ||
|
|
||
| [:octicons-file-code-24: Source][1] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| If you want to customize some (or all) of the translations for your language, | ||
| you may follow the guide on [theme extension][7] and create a new partial in | ||
| `partials/language`, e.g. `en-custom.html`. Next, look up the translation you | ||
| want to change in the [base translation][1] and add it to the partial. | ||
|
|
||
| Let's say you want to change "__Table of contents__" to "__On this page__": | ||
|
|
||
| ``` html | ||
| {% macro t(key) %}{{ { | ||
| "toc.title": "On this page" | ||
| }[key] }}{% endmacro %} | ||
| ``` | ||
|
|
||
| Then, add the following lines to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| language: en-custom | ||
| ``` | ||
|
|
||
| [7]: ../customization.md#extending-the-theme |
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Changing the logo and icons | ||
|
|
||
| When installing Material for MkDocs, you immediately get access to _over 7.000 | ||
| icons_ ready to be used for customization of specific parts of the theme and/or | ||
| when writing your documentation in Markdown. Not enough? You can also [add | ||
| additional icons][1] with minimal effort. | ||
|
|
||
| [1]: #additional-icons | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Logo | ||
|
|
||
| [:octicons-file-code-24: Source][2] · | ||
| :octicons-milestone-24: Default: `material/library` | ||
|
|
||
| There're two ways to specify a _logo_: it must be a valid path to [any icon | ||
| bundled with the theme][3], or to a user-provided image located in the `docs` | ||
| folder. Both can be set via `mkdocs.yml`: | ||
|
|
||
| === "Icon" | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| icon: | ||
| logo: material/library | ||
| ``` | ||
|
|
||
| === "Image" | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| logo: assets/logo.png | ||
| ``` | ||
|
|
||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html | ||
| [3]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons | ||
|
|
||
| ### Favicon | ||
|
|
||
| [:octicons-file-code-24: Source][4] · | ||
| :octicons-milestone-24: Default: `assets/images/favicon.png` | ||
|
|
||
| The _favicon_ can be changed to a path pointing to a user-provided image, which | ||
| must be located in the `docs` folder. It can be set via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| favicon: images/favicon.png | ||
| ``` | ||
|
|
||
| [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L74 | ||
|
|
||
| ### Icons | ||
|
|
||
| [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][5] | ||
|
|
||
| The [Emoji][5] extension, which is part of [Python Markdown Extensions][6], | ||
| adds the ability to __integrate icons__ in the `*.svg` file format, which are | ||
| inlined when [building your site][7]: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.emoji: | ||
| emoji_index: !!python/name:materialx.emoji.twemoji | ||
| emoji_generator: !!python/name:materialx.emoji.to_svg | ||
| ``` | ||
|
|
||
| The following icon sets are bundled with Material for MkDocs: | ||
|
|
||
| * :material-material-design: – [Material Design][8] | ||
| * :fontawesome-brands-font-awesome-flag: – [FontAwesome][9] | ||
| * :octicons-mark-github-16: – [Octicons][10] | ||
|
|
||
| If you want to add [additional icons][1], read on. | ||
|
|
||
| [5]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ | ||
| [6]: https://facelessuser.github.io/pymdown-extensions/ | ||
| [7]: ../creating-your-site.md#building-your-site | ||
| [8]: https://materialdesignicons.com/ | ||
| [9]: https://fontawesome.com/icons?d=gallery&m=free | ||
| [10]: https://octicons.github.com/ | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Additional icons | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-mortar-board-24: Difficulty: _moderate_ | ||
|
|
||
| In order to add additional icons, [extend the theme][11], and create a folder | ||
| named `.icons` in the [`custom_dir`][12] you want to use for overrides. Next, | ||
| add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you | ||
| downloaded and unpacked the [Bootstrap][13] icon set, and want to add it to | ||
| your project documentation. The structure of your project should look like this: | ||
|
|
||
| ``` sh | ||
| . | ||
| ├─ docs/ | ||
| │ └─ index.md | ||
| ├─ overrides/ | ||
| │ └─ .icons/ | ||
| │ └─ bootstrap/ | ||
| │ └─ *.svg | ||
| └─ mkdocs.yml | ||
| ``` | ||
|
|
||
| Then, add the following lines to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.emoji: | ||
| emoji_index: !!python/name:materialx.emoji.twemoji | ||
| emoji_generator: !!python/name:materialx.emoji.to_svg | ||
| options: | ||
| custom_icons: | ||
| - overrides/.icons | ||
| ``` | ||
|
|
||
| You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap | ||
| icons. | ||
|
|
||
| [11]: ../customization.md#extending-the-theme | ||
| [12]: https://www.mkdocs.org/user-guide/configuration/#custom_dir | ||
| [13]: https://icons.getbootstrap.com/ |
| @@ -0,0 +1,269 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Setting up navigation | ||
|
|
||
| A clear and concise navigation structure is an important aspect of good project | ||
| documentation. Material for MkDocs provides several options to configure the | ||
| behavior of navigational elements, some of those through _feature flags_. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Instant loading | ||
|
|
||
| [:octicons-file-code-24: Source][1] · | ||
| :octicons-unlock-24: Feature flag · | ||
| :octicons-beaker-24: Experimental | ||
|
|
||
| When _instant loading_ is activated, clicks on all internal links will be | ||
| intercepted and dispatched via [XHR][2] without fully reloading the page. It | ||
| can be enabled via `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| features: | ||
| - instant | ||
| ``` | ||
|
|
||
| The resulting page is parsed and injected and all event handlers and components | ||
| are rebound automatically. This means that __Material for MkDocs behaves like a | ||
| Single Page Application__, which is especially useful for large documentation | ||
| sites that come with a massive search index, as the search index will now | ||
| remain intact in-between document switches. | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts | ||
| [2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest | ||
|
|
||
| ### Navigation expansion | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-unlock-24: Feature flag · | ||
| :octicons-beaker-24: Experimental · | ||
| [:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders } | ||
|
|
||
| When `navigation.expand` is activated, the left sidebar will expand all | ||
| collapsible subsections by default, so the user doesn't have to do it manually. | ||
| It can be enabled via `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| features: | ||
| - navigation.expand | ||
| ``` | ||
|
|
||
| [3]: ../insiders.md | ||
|
|
||
| ### Navigation tabs | ||
|
|
||
| [:octicons-file-code-24: Source][4] · :octicons-unlock-24: Feature flag | ||
|
|
||
| When _tabs_ are activated, top-level sections are rendered in a menu layer | ||
| below the header on big screens (but not when the sidebar is hidden). It can be | ||
| enabled via `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| features: | ||
| - tabs | ||
| ``` | ||
|
|
||
| Note that all __top-level pages__ (i.e. all top-level entries that directly | ||
| refer to an `*.md` file) defined inside the [`nav`][5] entry of `mkdocs.yml` | ||
| will be grouped under the first tab which will receive the title of the first | ||
| page. | ||
|
|
||
| This means that there will effectively be no collapsible subsections for the | ||
| first tab, because each subsection is rendered as another tab. If you want more | ||
| fine-grained control, _i.e. collapsible subsections for the first tab_, you can | ||
| use __top-level sections__, so that the top-level is entirely made up of | ||
| sections. This is illustrated in the following example: | ||
|
|
||
| === "Top-level pages" | ||
|
|
||
| ``` yaml | ||
| nav: | ||
| - Tab 1 + Page 1.1 | ||
| - Page 1.2 | ||
| - Tab 2: | ||
| - Page 2.1 | ||
| - Page 2.2 | ||
| - Page 2.3 | ||
| - Page 1.3 | ||
| ``` | ||
|
|
||
| === "Top-level sections" | ||
|
|
||
| ``` yaml | ||
| nav: | ||
| - Tab 1: | ||
| - Page 1.1 | ||
| - Page 1.2 | ||
| - Page 1.3 | ||
| - Tab 2: | ||
| - Page 2.1 | ||
| - Page 2.2 | ||
| - Page 2.3 | ||
| ``` | ||
|
|
||
| Note that tabs are only shown for larger screens, so make sure that navigation | ||
| is plausible on mobile devices. As another example, see the [`mkdocs.yml`][6] | ||
| used to render these pages. | ||
|
|
||
| [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html | ||
| [5]: https://www.mkdocs.org/user-guide/configuration/#nav | ||
| [6]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml | ||
|
|
||
| ### Table of contents | ||
|
|
||
| [:octicons-file-code-24: Source][7] · [:octicons-workflow-24: Extension][8] | ||
|
|
||
| The [Table of contents][9] extension, which is part of the standard Markdown | ||
| library, provides some options that are supported by Material for MkDocs to | ||
| customize its appearance: | ||
|
|
||
| `permalink`{: #permalink } | ||
|
|
||
| : :octicons-milestone-24: Default: `false` – This option adds an anchor link | ||
| containing the paragraph symbol `¶` or another custom symbol at the end of | ||
| each headline, exactly like on the page you're currently viewing, which | ||
| Material for MkDocs will make appear on hover: | ||
|
|
||
| === "¶" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| permalink: true | ||
| ``` | ||
|
|
||
| === "⚓︎" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| permalink: ⚓︎ | ||
| ``` | ||
|
|
||
| `slugify`{: #slugify } | ||
|
|
||
| : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for | ||
| customization of the slug function. For some languages, the default may not | ||
| produce good and readable identifiers. Consider using another slug function | ||
| like for example those from [Python Markdown Extensions][10]: | ||
|
|
||
| === "Unicode" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| slugify: !!python/name:pymdownx.slugs.uslugify | ||
| ``` | ||
|
|
||
| === "Unicode, case-sensitive" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| slugify: !!python/name:pymdownx.slugs.uslugify_cased | ||
| ``` | ||
|
|
||
| `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 | ||
| documentation with deeply structured headings to decrease the length of the | ||
| table of contents, or to remove the table of contents altogether: | ||
|
|
||
| === "Hide levels 4-6" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| toc_depth: 3 | ||
| ``` | ||
|
|
||
| === "Hide table of contents" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - toc: | ||
| toc_depth: 0 | ||
| ``` | ||
|
|
||
| _Material for MkDocs doesn't provide official support for the other options of | ||
| this extension, so they may be supported but can also yield weird results. Use | ||
| them at your own risk._ | ||
|
|
||
| [7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html | ||
| [8]: https://python-markdown.github.io/extensions/toc/ | ||
| [9]: https://python-markdown.github.io/extensions/toc/#usage | ||
| [10]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ | ||
|
|
||
| #### Automatic hiding | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-unlock-24: Feature flag · | ||
| :octicons-beaker-24: Experimental · | ||
| [:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders } | ||
|
|
||
| When _autohiding_ is activated, the table of contents is automatically hidden | ||
| when the current page defines no headings, or only a single `h1` heading to be | ||
| rendered, so content stretches. | ||
|
|
||
| It can be enabled via `mkdocs.yml` with: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| features: | ||
| - toc.autohide | ||
| ``` | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Keyboard shortcuts | ||
|
|
||
| [:octicons-file-code-24: Source][11] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| Material for MkDocs includes several keyboard shortcuts that make it possible | ||
| to navigate your project documentation via keyboard. There're two modes: | ||
|
|
||
| `search`{: #search } | ||
|
|
||
| : This mode is active when the _search is focused_. It provides several key | ||
| bindings to make search accessible and navigable via keyboard: | ||
|
|
||
| * ++arrow-down++ , ++arrow-up++ : select next / previous result | ||
| * ++esc++ , ++tab++ : close search dialog | ||
| * ++enter++ : follow selected result | ||
|
|
||
| `global`{: #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 | ||
| are bound: | ||
|
|
||
| * ++f++ , ++s++ , ++slash++ : open search dialog | ||
| * ++p++ , ++comma++ : go to previous page | ||
| * ++n++ , ++period++ : go to next page | ||
|
|
||
| Let's say you want to bind some action to the ++x++ key. By using [additional | ||
| JavaScript][12], you can subscribe to the `keyboard$` observable and attach | ||
| your custom event listener: | ||
|
|
||
| ``` js | ||
| app.keyboard$.subscribe(function(key) { | ||
| if (key.mode === "global" && key.type === "x") { | ||
| /* Add custom keyboard handler here */ | ||
| key.claim() | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| The call to `#!js key.claim()` will essentially execute `#!js preventDefault()` | ||
| on the underlying event, so the keypress will not propagate further and touch | ||
| other event listeners. | ||
|
|
||
| [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts | ||
| [12]: ../customization.md#additional-javascript |
| @@ -0,0 +1,81 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Setting up site analytics | ||
|
|
||
| As with any other service offered on the web, understanding how your project | ||
| documentation is actually used can be an essential success factor. While | ||
| Material for MkDocs natively integrates with [Google Analytics][1], [other | ||
| analytics services][2] can be used, too. | ||
|
|
||
| [1]: https://developers.google.com/analytics | ||
| [2]: #other-analytics-providers | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Google Analytics | ||
|
|
||
| [:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_ | ||
|
|
||
| After heading over to your [Google Analytics][1] account to [create a new | ||
| property][4] in order to obtain a unique tracking id of the form | ||
| `UA-XXXXXXXX-X`, add it to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| google_analytics: | ||
| - UA-XXXXXXXX-X | ||
| - auto | ||
| ``` | ||
|
|
||
| [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html | ||
| [4]: https://support.google.com/analytics/answer/1042508 | ||
|
|
||
| #### Site search tracking | ||
|
|
||
| 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: | ||
|
|
||
| 1. Go to your Google Analytics __admin settings__ | ||
| 2. Select the property for the respective tracking code | ||
| 3. Go to the __view settings__ tab. | ||
| 4. Scroll down and enable __site search settings__ | ||
| 5. Set the __query parameter__ to `q`. | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Other analytics providers | ||
|
|
||
| [:octicons-file-code-24: Source][3] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| In order to integrate another analytics service provider offering an | ||
| asynchronous JavaScript-based tracking solution, you can [extend the theme][5] | ||
| and [override the `analytics` block][6]: | ||
|
|
||
| ``` html | ||
| {% block analytics %} | ||
| <!-- Add custom analytics integration here --> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| [5]: ../customization.md#extending-the-theme | ||
| [6]: ../customization.md#overriding-blocks | ||
|
|
||
| If you're using [instant loading][7], you may use the `location$` observable, | ||
| which will emit the current `URL` to listen for navigation events and register | ||
| a page view event with: | ||
|
|
||
| ``` js | ||
| app.location$.subscribe(function(url) { | ||
| /* Add custom page event tracking here */ | ||
| }) | ||
| ``` | ||
|
|
||
| Note that this must be integrated with [additional JavaScript][8], and cannot be | ||
| included as part of the `analytics` block, as it is included in the `head` of | ||
| the document. | ||
|
|
||
| [7]: setting-up-navigation.md#instant-loading | ||
| [8]: ../customization.md#additional-javascript |