1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-28 01:10:58 +01:00

Added nodes on snippets and fixed some documentation errors

This commit is contained in:
squidfunk 2020-07-23 15:34:43 +02:00
parent 186ea90e5f
commit c2a0238106
10 changed files with 131 additions and 96 deletions

View File

@ -46,24 +46,20 @@ markdown_extensions:
### SuperFences
[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
The [SuperFences][7] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of content blocks inside admonitions__,
and is therefore strongly recommended:
The [SuperFences][6] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code and content blocks inside
admonitions__, and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage
Admonitions follow a simple syntax: a block must start with `!!!`, followed
by a single keyword which is used as the [type qualifier][8] of the block. The
by a single keyword which is used as the [type qualifier][7] of the block. The
content of the block then follows on the next line, indented by four spaces.
_Example_:
@ -83,7 +79,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[8]: #supported-types
[7]: #supported-types
### Changing the title
@ -110,9 +106,9 @@ _Result_:
### Removing the title
Similar to [changing the title][9], the icon and title can be omitted entirely
Similar to [changing the title][8], the icon and title can be omitted entirely
by adding an empty string directly after the type qualifier. Note that this
will not work for [collapsible blocks][10].
will not work for [collapsible blocks][9].
_Example_:
@ -131,14 +127,14 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[9]: #changing-the-title
[10]: #collapsible-blocks
[8]: #changing-the-title
[9]: #collapsible-blocks
### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks. While the parser from the standard Markdown library
doesn't account for nested blocks, the [SuperFences][11] extension adds the
doesn't account for nested blocks, the [SuperFences][10] extension adds the
ability to nest arbitrary content inside admonitions.
_Example_:
@ -182,11 +178,11 @@ _Result_:
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
[11]: #superfences
[10]: #superfences
### Collapsible blocks
The [Details][12] extension adds support for rendering collapsible admonition
The [Details][11] extension adds support for rendering collapsible admonition
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
start with `???`.
@ -227,14 +223,14 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[12]: #details
[11]: #details
### Supported types
Following is a list of type qualifiers provided by Material for MkDocs, whereas
the default type, and thus fallback for unknown type qualifiers, is `note`:
`note`, `seealso`
`note`{: #note }, `seealso`
: !!! note
@ -242,7 +238,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`abstract`, `summary`, `tldr`
`abstract`{: #abstract }, `summary`, `tldr`
: !!! abstract
@ -250,7 +246,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`info`, `todo`
`info`{: #info}, `todo`
: !!! info
@ -258,7 +254,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`tip`, `hint`, `important`
`tip`{: #tip }, `hint`, `important`
: !!! tip
@ -266,7 +262,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`success`, `check`, `done`
`success`{: #success }, `check`, `done`
: !!! success
@ -274,7 +270,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`question`, `help`, `faq`
`question`{: #question }, `help`, `faq`
: !!! question
@ -282,7 +278,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`warning`, `caution`, `attention`
`warning`{: #warning }, `caution`, `attention`
: !!! warning
@ -290,7 +286,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`failure`, `fail`, `missing`
`failure`{: #failure }, `fail`, `missing`
: !!! failure
@ -298,7 +294,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`danger`, `error`
`danger`{: #danger }, `error`
: !!! danger
@ -306,7 +302,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`bug`
`bug`{: #bug }
: !!! bug
@ -314,7 +310,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`example`
`example`{: #example }
: !!! example
@ -322,7 +318,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`quote`, `cite`
`quote`{: #quote }, `cite`
: !!! quote

View File

@ -135,27 +135,11 @@ See the section on [inline code blocks][12] for usage information.
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[12]: #highlighting-inline-code-blocks
### SuperFences
### Keys
[: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/main/_typeset.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### Keys
[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
The [Keys][16] extension, which is part of [Python Markdown Extensions][5],
The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
can be enabled via `mkdocs.yml`:
@ -164,8 +148,34 @@ markdown_extensions:
- pymdownx.keys
```
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
[16]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
### SuperFences
The [SuperFences][15] 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
```
[15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### Snippets
The [Snippets][16] extension, which is also part of [Python Markdown
Extensions][5], allows to __insert content from other files__ or other, regular
content, and can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.snippets
```
[16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
## Usage
@ -271,11 +281,11 @@ The `#!python range()` function is used to generate a sequence of numbers.
[18]: #inlinehilite
### Displaying keyboard keys
### Adding keyboard keys
When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
See the [Python Markdown Extensions][16] documentation for a list of all
available keys.
Consult the [Python Markdown Extensions][16] documentation to learn about all
available short key codes.
_Example_:
@ -288,3 +298,29 @@ _Result_:
++ctrl+alt+del++
[19]: #keys
### Adding external files
When [Snippets][20] is enabled, content from other files can be inserted, which
is especially useful to reference and embed the contents of source files
directly into your project documentation.
_Example_:
```` markdown
```
--8<-- ".browserslistrc"
```
````
_Result_:
```
--8<-- ".browserslistrc"
```
Note that [Snippets][20] is not limited to code blocks, but can be used anywhere
in a Markdown file to put repeating content into separate files, which is also
explained in the [official documentation][16].
[20]: #snippets

View File

@ -28,19 +28,16 @@ markdown_extensions:
### SuperFences
[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5]
The [SuperFences][5] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code blocks inside tabs__, and is
therefore strongly recommended:
The [SuperFences][4] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code and content blocks inside
tabs__, and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage
@ -138,9 +135,9 @@ _Result_:
### Embedded content
Content tabs can contain arbitrary nested content, including further content
tabs, and can be nested in other blocks like [admonitions][6], [details][7] or
blockquotes:
When [SuperFences][5] is enabled, content tabs can contain arbitrary nested
content, including further content tabs, and can be nested in other blocks like
[admonitions][6], [details][7] or blockquotes:
_Example_:
@ -216,5 +213,6 @@ _Result_:
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
[5]: #superfences
[6]: admonitions.md
[7]: admonitions.md#details

View File

@ -15,7 +15,7 @@ are supported through extensions.
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Definition List][1] extension, which is part of the standard Markdown
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`:

View File

@ -10,7 +10,7 @@ template: overrides/main.html
### Metadata
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
[:octicons-workflow-24: Extension][1]
The [Metadata][1] extension, which is part of the standard Markdown
library, adds the ability to add custom metadata to a document and can be
@ -22,7 +22,6 @@ markdown_extensions:
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[2]: https://python-markdown.github.io/extensions/meta_data/
## Usage

View File

@ -15,9 +15,12 @@ integrated, too.
### Disqus
First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate
[: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][3], and add it to `mkdocs.yml`:
[shortname][4], and add it to `mkdocs.yml`:
``` yaml
extra:
@ -26,14 +29,18 @@ extra:
This will insert a comment system on _every page, except the index page_.
[2]: https://www.mkdocs.org/user-guide/configuration/#site_url
[3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
[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
## Customization
### Selective integration
If the [Metadata][4] extension is enabled, you can disable or enable Disqus for
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If the [Metadata][5] 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"
@ -52,4 +59,4 @@ specific pages by adding the following to the front matter of a page:
---
```
[4]: ../reference/meta-tags.md#metadata
[5]: ../reference/meta-tags.md#metadata

View File

@ -40,11 +40,11 @@ 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
[3]: https://www.mkdocs.org/user-guide/configuration/#repo_name
### Repository icon
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default:
[: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

View File

@ -30,7 +30,7 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L120-L139
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L116-L140
[3]: https://fonts.google.com/specimen/Roboto
### Proportional font

View File

@ -57,11 +57,11 @@ theme:
### Icons
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][5]
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
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 into the HTML when [building your site][8]:
inlined into the HTML when [building your site][7]:
``` yaml
markdown_extensions:
@ -72,19 +72,18 @@ markdown_extensions:
The following icon sets are bundled with Material for MkDocs:
* :material-material-design: [Material Design][9]
* :fontawesome-brands-font-awesome-flag: [FontAwesome][10]
* :fontawesome-brands-github: [Octicons][11]
* :material-material-design: [Material Design][8]
* :fontawesome-brands-font-awesome-flag: [FontAwesome][9]
* :fontawesome-brands-github: [Octicons][10]
If you want to add [additional icons][1], read on.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: ../creating-your-site.md#building-your-site
[9]: https://materialdesignicons.com/
[10]: https://fontawesome.com/icons?d=gallery&m=free
[11]: https://octicons.github.com/
[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
@ -93,10 +92,10 @@ If you want to add [additional icons][1], read on.
[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _moderate_
In order to add additional icons, [extend the theme][13] and create a folder
named `.icons` in the [`custom_dir`][14] you want to use for overrides. Next,
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][15] icon set, and want to add it to
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
@ -125,6 +124,6 @@ markdown_extensions:
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
icons.
[13]: ../customization.md#extending-the-theme
[14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[15]: https://icons.getbootstrap.com/
[11]: ../customization.md#extending-the-theme
[12]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[13]: https://icons.getbootstrap.com/

View File

@ -47,7 +47,7 @@ search tracking:
### Using other analytics services
[:octicons-file-code-24: Source][2] ·
[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to integrate another analytics service provider offering an
@ -65,7 +65,7 @@ and [override the `analytics` block][6]:
### Using instant loading
[:octicons-file-code-24: Source][2] ·
[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you're using [instant loading][7], you may use the `location$` observable,