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

Added lists reference and repository guide

Browse Source
This commit is contained in:
squidfunk 2020-07-21 13:33:44 +02:00
parent be485a25e5
commit 0f6357994a
16 changed files with 444 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/guides/adding-a-git-repository.md
View File

@ -4,31 +4,96 @@ template: overrides/main.html
# Adding a git repository # Adding a git repository
- link edit button If your documentation is related to source code, Material for MkDocs provides
- link related source file (via metadata) the ability to display information to the project's repository as part of the
static site, including statistics like stars and forks. Furthermore, certain
documents can be linked to specific source files.
## Configuration ## Configuration
To include a link to the repository of your project within your documentation, In order to display a link to the repository of your project as part of your
set the following variables via your project's `mkdocs.yml`: documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your
repository, e.g.:
``` yaml ``` yaml
repo_name: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material repo_url: https://github.com/squidfunk/mkdocs-material
``` ```
The name of the repository will be rendered next to the search bar on big 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. 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 shown. Additionally, for GitHub and GitLab, the number of stars and forks is
Note that the repository icon can be explicitly set through `theme.icon.repo`. automatically requested and rendered for _public repositories_.
!!! question "Why is there an edit button at the top of every article?" [1]: https://www.mkdocs.org/user-guide/configuration/#repo_url
If the `repo_url` is set to a GitHub or BitBucket repository, and the ### Repository name
`repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
edit button will appear at the top of every article. This is the automatic
behavior that MkDocs implements. See the [MkDocs documentation][20] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit
button is shown or not.
[20]: https://www.mkdocs.org/user-guide/configuration/#edit_uri [: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_url
### Repository icon
[:octicons-file-code-24: Source][1] · :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 repository icons:
- :fontawesome-brands-git: – `:fontawesome-brands-git:`
- :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#L299-L308
[6]: https://github.com/
[7]: https://about.gitlab.com/
[8]: https://bitbucket.org/
[9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri

6
docs/guides/changing-colors.md
View File

@ -7,7 +7,7 @@ template: overrides/main.html
As any good Material Design implementation, Material for MkDocs supports As any good Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through 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 `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand identity by using [CSS variables][2]. fit your brand's identity by using [CSS variables][2].
[1]: http://www.materialui.co/colors [1]: http://www.materialui.co/colors
[2]: #customization [2]: #customization
@ -251,5 +251,5 @@ colors or neutral colors:
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss
[7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties [7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[8]: ../customization.md#additional-stylesheets [8]: ../customization.md#additional-stylesheets
[9]: ../writing/code-blocks.md [9]: ../reference/code-blocks.md
[10]: ../writing/admonitions.md [10]: ../reference/admonitions.md

90
docs/guides/changing-the-language.md
View File

@ -14,7 +14,7 @@ search can be configured to use a language-specific stemmer (if available).
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en` [:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
You can set the language from `mkdocs.yml` with: You can set the _site language_ from `mkdocs.yml` with:
``` yaml ``` yaml
theme: theme:
@ -24,49 +24,49 @@ theme:
The following languages are supported: The following languages are supported:
<ul class="tx-columns"> <ul class="tx-columns">
<li><code>af</code> / Afrikaans</li> <li><code>af</code> – Afrikaans</li>
<li><code>ar</code> / Arabic</li> <li><code>ar</code> – Arabic</li>
<li><code>bn</code> / Bengali (Bangla)</li> <li><code>bn</code> – Bengali (Bangla)</li>
<li><code>ca</code> / Catalan</li> <li><code>ca</code> – Catalan</li>
<li><code>cs</code> / Czech</li> <li><code>cs</code> – Czech</li>
<li><code>da</code> / Danish</li> <li><code>da</code> – Danish</li>
<li><code>de</code> / German</li> <li><code>de</code> – German</li>
<li><code>en</code> / English</li> <li><code>en</code> – English</li>
<li><code>es</code> / Spanish</li> <li><code>es</code> – Spanish</li>
<li><code>et</code> / Estonian</li> <li><code>et</code> – Estonian</li>
<li><code>fa</code> / Persian (Farsi)</li> <li><code>fa</code> – Persian (Farsi)</li>
<li><code>fi</code> / Finnish</li> <li><code>fi</code> – Finnish</li>
<li><code>fr</code> / French</li> <li><code>fr</code> – French</li>
<li><code>gl</code> / Galician</li> <li><code>gl</code> – Galician</li>
<li><code>gr</code> / Greek</li> <li><code>gr</code> – Greek</li>
<li><code>he</code> / Hebrew</li> <li><code>he</code> – Hebrew</li>
<li><code>hi</code> / Hindi</li> <li><code>hi</code> – Hindi</li>
<li><code>hr</code> / Croatian</li> <li><code>hr</code> – Croatian</li>
<li><code>hu</code> / Hungarian</li> <li><code>hu</code> – Hungarian</li>
<li><code>id</code> / Indonesian</li> <li><code>id</code> – Indonesian</li>
<li><code>it</code> / Italian</li> <li><code>it</code> – Italian</li>
<li><code>ja</code> / Japanese</li> <li><code>ja</code> – Japanese</li>
<li><code>kr</code> / Korean</li> <li><code>kr</code> – Korean</li>
<li><code>my</code> / Burmese</li> <li><code>my</code> – Burmese</li>
<li><code>nl</code> / Dutch</li> <li><code>nl</code> – Dutch</li>
<li><code>nn</code> / Norwegian (Nynorsk)</li> <li><code>nn</code> – Norwegian (Nynorsk)</li>
<li><code>no</code> / Norwegian</li> <li><code>no</code> – Norwegian</li>
<li><code>pl</code> / Polish</li> <li><code>pl</code> – Polish</li>
<li><code>pt</code> / Portuguese</li> <li><code>pt</code> – Portuguese</li>
<li><code>ro</code> / Romanian</li> <li><code>ro</code> – Romanian</li>
<li><code>ru</code> / Russian</li> <li><code>ru</code> – Russian</li>
<li><code>sh</code> / Serbo-Croatian</li> <li><code>sh</code> – Serbo-Croatian</li>
<li><code>si</code> / Slovenian</li> <li><code>si</code> – Slovenian</li>
<li><code>sk</code> / Slovak</li> <li><code>sk</code> – Slovak</li>
<li><code>sr</code> / Serbian</li> <li><code>sr</code> – Serbian</li>
<li><code>sv</code> / Swedish</li> <li><code>sv</code> – Swedish</li>
<li><code>th</code> / Thai</li> <li><code>th</code> – Thai</li>
<li><code>tr</code> / Turkish</li> <li><code>tr</code> – Turkish</li>
<li><code>uk</code> / Ukrainian</li> <li><code>uk</code> – Ukrainian</li>
<li><code>vi</code> / Vietnamese</li> <li><code>vi</code> – Vietnamese</li>
<li><code>zh</code> / Chinese (Simplified)</li> <li><code>zh</code> – Chinese (Simplified)</li>
<li><code>zh-Hant</code> / Chinese (Traditional)</li> <li><code>zh-Hant</code> – Chinese (Traditional)</li>
<li><code>zh-TW</code> / Chinese (Taiwanese)</li> <li><code>zh-TW</code> – Chinese (Taiwanese)</li>
<li> <li>
<a href="https://bit.ly/38F5RCa"> <a href="https://bit.ly/38F5RCa">
Add language Add language
@ -97,7 +97,7 @@ more information.
:octicons-milestone-24: Default: _automatically set_ :octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) directionality which is inferred from the supports `rtl` (right-to-left) _directionality_ which is inferred from the
selected language, but can also be set with: selected language, but can also be set with:
``` yaml ``` yaml

38
docs/guides/setting-up-navigation.md
View File

@ -50,8 +50,9 @@ theme:
``` ```
Note that all __top-level pages__ (i.e. all top-level entries that directly Note that all __top-level pages__ (i.e. all top-level entries that directly
refer to an `*.md` file) defined inside the `nav` entry of `mkdocs.yml` will be refer to an `*.md` file) defined inside the [`nav`][4] entry of `mkdocs.yml`
grouped under the first tab which will receive the title of the first page. 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 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 first tab, because each subsection is rendered as another tab. If you want more
@ -87,17 +88,18 @@ sections. This is illustrated in the following example:
``` ```
Note that tabs are only shown for larger screens, so make sure that navigation 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`][4] is plausible on mobile devices. As another example, see the [`mkdocs.yml`][5]
used to render these pages. used to render these pages.
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml [4]: https://www.mkdocs.org/user-guide/configuration/#nav
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
### Table of contents ### Table of contents
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6] [:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
The [Table of contents][7] extension, which is part of the standard Markdown The [Table of contents][8] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to library, provides some options that are supported by Material for MkDocs to
customize its appearance: customize its appearance:
@ -129,7 +131,7 @@ customize its appearance:
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not customization of the slug function. For some languages, the default may not
produce good and readable identifiers. Consider using another slug function produce good and readable identifiers. Consider using another slug function
like for example those from [Python Markdown Extensions][8]: like for example those from [Python Markdown Extensions][9]:
=== "Unicode" === "Unicode"
@ -174,21 +176,21 @@ _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 this extension, so they may be supported but can also yield weird results. Use
them at your own risk._ them at your own risk._
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[6]: https://python-markdown.github.io/extensions/toc/ [7]: https://python-markdown.github.io/extensions/toc/
[7]: https://python-markdown.github.io/extensions/toc/#usage [8]: https://python-markdown.github.io/extensions/toc/#usage
[8]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ [9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
## Customization ## Customization
[:octicons-file-code-24: Source][9] · [:octicons-file-code-24: Source][10] ·
:octicons-mortar-board-24: Difficulty: moderate :octicons-mortar-board-24: Difficulty: moderate
All navigational elements are defined as partials and can be overridden through All navigational elements are defined as partials and can be overridden through
[theme extension][10] by [overriding partials][11] or [blocks][12], i.e. [theme extension][11] by [overriding partials][12] or [blocks][13], i.e.
`site_nav` which contains both sidebars, `tabs` and `footer`. `site_nav` which contains both sidebars, `tabs` and `footer`.
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials [10]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials
[10]: ../customization.md#extending-the-theme [11]: ../customization.md#extending-the-theme
[11]: ../customization.md#overriding-partials [12]: ../customization.md#overriding-partials
[12]: ../customization.md#overriding-blocks [13]: ../customization.md#overriding-blocks

38
docs/guides/setting-up-site-search.md
View File

@ -59,25 +59,25 @@ The following options are supported:
The following languages are supported: The following languages are supported:
<ul class="tx-columns"> <ul class="tx-columns">
<li><code>ar</code> / Arabic</li> <li><code>ar</code> – Arabic</li>
<li><code>da</code> / Danish</li> <li><code>da</code> – Danish</li>
<li><code>du</code> / Dutch</li> <li><code>du</code> – Dutch</li>
<li><code>en</code> / English</li> <li><code>en</code> – English</li>
<li><code>fi</code> / Finnish</li> <li><code>fi</code> – Finnish</li>
<li><code>fr</code> / French</li> <li><code>fr</code> – French</li>
<li><code>de</code> / German</li> <li><code>de</code> – German</li>
<li><code>hu</code> / Hungarian</li> <li><code>hu</code> – Hungarian</li>
<li><code>it</code> / Italian</li> <li><code>it</code> – Italian</li>
<li><code>ja</code> / Japanese</li> <li><code>ja</code> – Japanese</li>
<li><code>no</code> / Norwegian</li> <li><code>no</code> – Norwegian</li>
<li><code>pt</code> / Portuguese</li> <li><code>pt</code> – Portuguese</li>
<li><code>ro</code> / Romanian</li> <li><code>ro</code> – Romanian</li>
<li><code>ru</code> / Russian</li> <li><code>ru</code> – Russian</li>
<li><code>es</code> / Spanish</li> <li><code>es</code> – Spanish</li>
<li><code>sv</code> / Swedish</li> <li><code>sv</code> – Swedish</li>
<li><code>th</code> / Thai</li> <li><code>th</code> – Thai</li>
<li><code>tr</code> / Turkish</li> <li><code>tr</code> – Turkish</li>
<li><code>vi</code> / Vietnamese</li> <li><code>vi</code> – Vietnamese</li>
</ul> </ul>
_Material for MkDocs also tries to support languages which are not part of _Material for MkDocs also tries to support languages which are not part of

32
docs/writing/admonitions.md → docs/reference/admonitions.md
View File

@ -4,7 +4,7 @@ template: overrides/main.html
# Admonitions # Admonitions
Admonitions, also know as _call-outs_, are an excellent choice for including Admonitions, also known as _call-outs_, are an excellent choice for including
side content without significantly interrupting the document flow. Material for side content without significantly interrupting the document flow. Material for
MkDocs provides several different types of admonitions and allows for the MkDocs provides several different types of admonitions and allows for the
inclusion and nesting of arbitrary content. inclusion and nesting of arbitrary content.
@ -32,7 +32,7 @@ markdown_extensions:
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4] [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Details][4] extension, which is part of [Python Markdown Extensions][5], The [Details][4] extension, which is part of [Python Markdown Extensions][5],
adds the abilty to make admonitions collapsible. It can be enabled from adds the ability to __make admonitions collapsible__. It can be enabled from
`mkdocs.yml`: `mkdocs.yml`:
``` yaml ``` yaml
@ -49,8 +49,8 @@ markdown_extensions:
[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7] [:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
The [SuperFences][7] extension, which is also part of [Python Markdown The [SuperFences][7] extension, which is also part of [Python Markdown
Extensions][5], allows for the arbitrary nesting of content inside blocks, and Extensions][5], allows for the __nesting of content blocks inside admonitions__,
is therefore strongly recommended: and is therefore strongly recommended:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -87,9 +87,9 @@ _Result_:
### Changing the title ### Changing the title
By default, the admonition title will equal the type qualifier in titlecase. By default, the title will equal the type qualifier in titlecase. However, it
However, it can be changed to a custom string by adding a quoted string after can be changed by adding a quoted string containing valid Markdown (including
the type qualifier. links, formatting, ...) after the type qualifier.
_Example_: _Example_:
@ -110,8 +110,9 @@ _Result_:
### Removing the title ### Removing the title
Similar to [changing the title][9], the icon and title can be omitted by adding Similar to [changing the title][9], the icon and title can be omitted entirely
an empty string directly after the type qualifier. by adding an empty string directly after the type qualifier. Note that this
will not work for [collapsible blocks][10].
_Example_: _Example_:
@ -131,13 +132,14 @@ _Result_:
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[9]: #changing-the-title [9]: #changing-the-title
[10]: #collapsible-blocks
### Embedded content ### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists, Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks. While the parser from the standard Markdown library paragraphs and other blocks. While the parser from the standard Markdown library
doesn't account for nested code blocks, the [SuperFences][10] extension adds doesn't account for nested blocks, the [SuperFences][11] extension adds the
the ability to nest arbitrary content inside admonitions. ability to nest arbitrary content inside admonitions.
_Example_: _Example_:
@ -180,11 +182,11 @@ _Result_:
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
[10]: #superfences [11]: #superfences
### Collapsible blocks ### Collapsible blocks
The [Details][11] extension adds support for rendering collapsible admonition The [Details][12] extension adds support for rendering collapsible admonition
blocks. This is useful for FAQs or content that is of secondary nature. A blocks. This is useful for FAQs or content that is of secondary nature. A
details block follows the syntax and semantics of admonition blocks, but must details block follows the syntax and semantics of admonition blocks, but must
start with `???`. start with `???`.
@ -206,7 +208,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
Adding a `+` after `???` will render the block open on page load: Adding a `+` after `???` will render the block as open on page load:
_Example_: _Example_:
@ -225,7 +227,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[11]: #details [12]: #details
### Supported types ### Supported types

72
docs/writing/code-blocks.md → docs/reference/code-blocks.md
View File

@ -15,9 +15,10 @@ during runtime using a JavaScript syntax highlighter.
### Highlight ### Highlight
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
:octicons-zap-24: Supersedes: [CodeHilite][4]
The [Highlight][3] extension, which is part of [Python Markdown Extensions][4], The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
integrates with Material for MkDocs and provides several options for integrates with Material for MkDocs and provides several options for
configuring syntax highlighting of code blocks: configuring syntax highlighting of code blocks:
@ -26,7 +27,7 @@ configuring syntax highlighting of code blocks:
: :octicons-milestone-24: Default: `true` · This option allows to control : :octicons-milestone-24: Default: `true` · This option allows to control
whether highlighting should be carried out during build time by whether highlighting should be carried out during build time by
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
necessary [additional stylesheets][5] and [JavaScript][6] if you want to necessary [additional stylesheets][6] and [JavaScript][7] if you want to
use the latter: use the latter:
=== "Pygments" === "Pygments"
@ -45,12 +46,12 @@ configuring syntax highlighting of code blocks:
use_pygments: false use_pygments: false
``` ```
??? example "Syntax highlighting with [Highlight.js][7]" ??? example "Syntax highlighting with Highlight.js"
Highlight.js can be integrated by creating an [additional JavaScript][6] [Highlight.js][8] can be integrated by creating an [additional
file initializing the highlighter and including the respective JavaScript][7] file initializing the highlighter and including the
stylesheet and JavaScript from a [CDN][8] serving Highlight.js in respective stylesheet and JavaScript from a [CDN][9] serving
`mkdocs.yml`: Highlight.js in `mkdocs.yml`:
=== "docs/javascripts/extra.js" === "docs/javascripts/extra.js"
@ -74,7 +75,7 @@ configuring syntax highlighting of code blocks:
: :octicons-milestone-24: Default: `false` · This option will add line numbers : :octicons-milestone-24: Default: `false` · This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all to _all_ code blocks. If you wish to add line numbers to _some_, but not all
code blocks, consult the section on [adding line numbers][9] later in this code blocks, consult the section on [adding line numbers][10] later in this
document, which also contains some tips on working with line numbers: document, which also contains some tips on working with line numbers:
``` yaml ``` yaml
@ -107,20 +108,21 @@ them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_highlight.scss [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_highlight.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/ [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[4]: https://facelessuser.github.io/pymdown-extensions/ [4]: https://python-markdown.github.io/extensions/code_hilite/
[5]: ../customization.md#additional-stylesheets [5]: https://facelessuser.github.io/pymdown-extensions/
[6]: ../customization.md#additional-javascript [6]: ../customization.md#additional-stylesheets
[7]: https://highlightjs.org/ [7]: ../customization.md#additional-javascript
[8]: https://cdnjs.com/libraries/highlight.js/ [8]: https://highlightjs.org/
[9]: #adding-line-numbers [9]: https://cdnjs.com/libraries/highlight.js/
[10]: #adding-line-numbers
### InlineHilite ### InlineHilite
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][10] [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
The [InlineHilite][10] extension, which is part of [Python Markdown The [InlineHilite][11] extension, which is part of [Python Markdown
Extensions][4] also integrates with Material for MkDocs and adds support for Extensions][5] also integrates with Material for MkDocs and adds support for
syntax highlighting of inline code blocks. It's built on top of the __syntax highlighting of inline code blocks__. It's built on top of the
[Highlight][3] extension and can be enabled from `mkdocs.yml`: [Highlight][3] extension and can be enabled from `mkdocs.yml`:
``` yaml ``` yaml
@ -128,10 +130,26 @@ markdown_extensions:
- pymdownx.inlinehilite - pymdownx.inlinehilite
``` ```
See the section on [inline code blocks][11] for usage information. See the section on [inline code blocks][12] for usage information.
[10]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[11]: #inline-code-blocks [12]: #inline-code-blocks
### SuperFences
[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
The [SuperFences][14] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code blocks inside other blocks__,
and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage ## Usage
@ -143,7 +161,7 @@ a JavaScript syntax highlighter.
Code blocks must be enclosed with two separate lines containing three backticks. Code blocks must be enclosed with two separate lines containing three backticks.
To add code highlighting to those blocks, add the language short name directly To add code highlighting to those blocks, add the language short name directly
after the opening block. See the [list of available lexers][12] to find the after the opening block. See the [list of available lexers][15] to find the
short name for a given language. short name for a given language.
_Example_: _Example_:
@ -160,7 +178,7 @@ _Result_:
import tensorflow as tf import tensorflow as tf
``` ```
[12]: https://pygments.org/docs/lexers/ [15]: https://pygments.org/docs/lexers/
### Adding line numbers ### Adding line numbers
@ -221,9 +239,9 @@ def bubble_sort(items):
### Inline code blocks ### Inline code blocks
When [InlineHilite][13] is enabled, inline code blocks can be highlighted by When [InlineHilite][16] is enabled, inline code blocks can be highlighted by
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
the [language short name][12]. the [language short name][15].
_Example_: _Example_:
@ -235,4 +253,4 @@ _Result_:
The `#!python range()` function is used to generate a sequence of numbers. The `#!python range()` function is used to generate a sequence of numbers.
[13]: #inlinehilite [16]: #inlinehilite

3
docs/writing/content-tabs.md → docs/reference/content-tabs.md
View File

@ -6,8 +6,7 @@ template: overrides/main.html
Sometimes, it's desirable to group alternative content under different tabs, Sometimes, it's desirable to group alternative content under different tabs,
e.g. when describing how to access an API from different languages or e.g. when describing how to access an API from different languages or
environments. Material for MkDocs allows for beautiful and functional tabbed environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.
content, including code blocks or body copy.
## Configuration ## Configuration

0
docs/writing/footnotes.md → docs/reference/footnotes.md
View File

202
docs/reference/lists.md Normal file
View File

@ -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 Lists
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Definition List][1] extension, which is part of the standard Markdown
library, adds the ability to add definitions lists to a document and can be
enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- def_list
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_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`
: :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`
: :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/extensions/pymdown/_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 renderer.
_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-lists
### 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

4
material/assets/manifest.json
View File

@ -5,8 +5,8 @@
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map", "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js", "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map", "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.1b6dc5da.min.css", "assets/stylesheets/main.css": "assets/stylesheets/main.f03f5644.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.1b6dc5da.min.css.map", "assets/stylesheets/main.css.map": "assets/stylesheets/main.f03f5644.min.css.map",
"assets/stylesheets/overrides.css": "assets/stylesheets/overrides.0ad0ad40.min.css", "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.0ad0ad40.min.css",
"assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.0ad0ad40.min.css.map", "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.0ad0ad40.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.87445083.min.css", "assets/stylesheets/palette.css": "assets/stylesheets/palette.87445083.min.css",

1
material/assets/stylesheets/main.1b6dc5da.min.css.map
View File

File diff suppressed because one or more lines are too long

2
material/assets/stylesheets/main.1b6dc5da.min.css → material/assets/stylesheets/main.f03f5644.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.f03f5644.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -41,7 +41,7 @@
{% endif %} {% endif %}
{% endblock %} {% endblock %}
{% block styles %} {% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.1b6dc5da.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/main.f03f5644.min.css' | url }}">
{% if palette.scheme or palette.primary or palette.accent %} {% if palette.scheme or palette.primary or palette.accent %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.87445083.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.87445083.min.css' | url }}">
{% endif %} {% endif %}

11
mkdocs.yml
View File

@ -131,11 +131,12 @@ nav:
- Customization: customization.md - Customization: customization.md
#- Troubleshooting: troubleshooting.md #- Troubleshooting: troubleshooting.md
- Data privacy: data-privacy.md - Data privacy: data-privacy.md
- Writing: - Reference:
- Admonitions: writing/admonitions.md - Admonitions: reference/admonitions.md
- Code blocks: writing/code-blocks.md - Code blocks: reference/code-blocks.md
- Content tabs: writing/content-tabs.md - Content tabs: reference/content-tabs.md
- Footnotes: writing/footnotes.md - Footnotes: reference/footnotes.md
- Lists: reference/lists.md
- Guides: - Guides:
- Changing colors: guides/changing-colors.md - Changing colors: guides/changing-colors.md
- Changing the fonts: guides/changing-the-fonts.md - Changing the fonts: guides/changing-the-fonts.md