mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-09-24 03:18:21 +02:00
Updated code block reference
This commit is contained in:
squidfunk
parent
b8becde3bb
commit
df88640208
@ -150,7 +150,7 @@ The following features are currently exclusively available to sponsors:
|
||||
- [x] [Stay on page when switching versions][28]
|
||||
- [x] [Version warning][26]
|
||||
- [x] [Custom admonition icons][31]
|
||||
- [x] [Code block annotations][25]
|
||||
- [x] [Code annotations][25]
|
||||
- [x] [Anchor tracking ][24]
|
||||
- [x] [Mermaid.js integration][27]
|
||||
|
||||
@ -173,7 +173,7 @@ the public for general availability.
|
||||
#### $ 4,000 – Ghost Pepper
|
||||
|
||||
- [x] [Anchor tracking][24]
|
||||
- [x] [Code block annotations][25]
|
||||
- [x] [Code annotations][25]
|
||||
- [x] [Version warning][26]
|
||||
|
||||
[24]: ../setup/setting-up-navigation.md#anchor-tracking
|
||||
|
||||
@ -11,43 +11,31 @@ enable site-wide glossaries.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Abbreviations
|
||||
|
||||
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
||||
|
||||
The [Abbreviations][2] extension, which is part of the standard Markdown
|
||||
library, allows to __add additional content to parts of the text which are then
|
||||
shown on hover__, e.g. for glossaries:
|
||||
This configuration enables abbreviations, and allows to build a simple
|
||||
project-wide glossary sourcing definitions from a central location. Add the
|
||||
following line to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- abbr
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
|
||||
[2]: https://python-markdown.github.io/extensions/abbreviations/
|
||||
|
||||
### Snippets
|
||||
|
||||
The [Snippets][3] extension, which is part of [Python Markdown Extensions][4],
|
||||
allows to __insert content from other files__ or other, regular content, and can
|
||||
be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.snippets
|
||||
```
|
||||
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/
|
||||
See additional configuration options:
|
||||
|
||||
- [Abbreviations]
|
||||
- [Snippets]
|
||||
|
||||
[Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
|
||||
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding abbreviations
|
||||
|
||||
When the [Abbreviations][5] extension is enabled, abbreviations can be defined
|
||||
with a special syntax similar to URLs and [footnotes][6] at any point in the
|
||||
Markdown document.
|
||||
Abbreviations can be defined by using a special syntax similar to URLs and
|
||||
[footnotes], starting with a `*` and immediately followed by the term or
|
||||
acronym to be associated in square brackets.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -65,18 +53,23 @@ The HTML specification is maintained by the W3C.
|
||||
*[HTML]: Hyper Text Markup Language
|
||||
*[W3C]: World Wide Web Consortium
|
||||
|
||||
[5]: #abbreviations_1
|
||||
[6]: footnotes.md
|
||||
[footnotes]: footnotes.md
|
||||
|
||||
### Adding a glossary
|
||||
|
||||
When [Snippets][7] is enabled, content from other files can be embedded, which
|
||||
is especially useful to include abbreviations from a central file – a glossary –
|
||||
and embed them into any other file.
|
||||
The [Snippets] extension can be used to implement a simple glossary, by moving
|
||||
all abbreviations in a dedicated file[^1] and include it with the
|
||||
[`--8<--` notation][Snippets notation] at the end of each document.
|
||||
|
||||
[^1]:
|
||||
It's highly recommended to put the Markdown file containing the
|
||||
abbreviations outside of the `docs` folder (here, a folder with the name
|
||||
`includes` is used), as MkDocs might otherwise complain about an
|
||||
unreferenced file.
|
||||
|
||||
_Example_:
|
||||
|
||||
=== "`docs/page.md`"
|
||||
=== ":octicons-file-code-16: docs/page.md"
|
||||
|
||||
```` markdown
|
||||
The HTML specification is maintained by the W3C.
|
||||
@ -84,7 +77,7 @@ _Example_:
|
||||
--8<-- "includes/abbreviations.md"
|
||||
````
|
||||
|
||||
=== "`includes/abbreviations.md`"
|
||||
=== ":octicons-file-code-16: includes/abbreviations.md"
|
||||
|
||||
```` markdown
|
||||
*[HTML]: Hyper Text Markup Language
|
||||
@ -95,8 +88,4 @@ _Result_:
|
||||
|
||||
The HTML specification is maintained by the W3C.
|
||||
|
||||
_Remember to locate the Markdown file containing the definitions outside of the_
|
||||
`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
|
||||
unreferenced file._
|
||||
|
||||
[7]: #snippets
|
||||
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
|
||||
|
||||
@ -11,9 +11,9 @@ inclusion and nesting of arbitrary content.
|
||||
|
||||
## Configuration
|
||||
|
||||
The following configuration enables admonitions, allows to make them collapsible
|
||||
and to nest arbitrary content inside admonition bodies. Add the following lines
|
||||
to `mkdocs.yml`:
|
||||
This configuration enables admonitions, allows to make them collapsible and to
|
||||
nest arbitrary content inside admonition bodies. Add the following lines to
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -111,9 +111,9 @@ _Result_:
|
||||
|
||||
### Collapsible blocks
|
||||
|
||||
If the [Details] extension is enabled and an admonition is started with `???`
|
||||
instead of `!!!`, the admonition is rendered as a collapsible block with a
|
||||
small marker on the right side.
|
||||
When [Details] is enabled and an admonition block is started with `???` instead
|
||||
of `!!!`, the admonition is rendered as a collapsible block with a small toggle
|
||||
on the right side.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -155,6 +155,9 @@ _Result_:
|
||||
|
||||
### Inline blocks
|
||||
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: 7.0.0 ... present][Inline support]
|
||||
|
||||
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
|
||||
them to the right using the `inline` + `end` modifiers, or to the left using
|
||||
only the `inline` modifier.
|
||||
@ -208,6 +211,8 @@ prior to the content block you want to place them beside. If there's
|
||||
insufficient space to render the admonition next to the block, the admonition
|
||||
will stretch to the full width of the viewport, e.g. on mobile viewports.
|
||||
|
||||
[Inline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
|
||||
|
||||
### Supported types
|
||||
|
||||
Following is a list of type qualifiers provided by Material for MkDocs, whereas
|
||||
@ -318,7 +323,8 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
|
||||
### Changing the icons
|
||||
|
||||
> This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders }
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
|
||||
|
||||
Each of the supported admonition types has a distinct icon, which can be changed
|
||||
to any icon bundled with the theme. Just set the name of the admonition type to
|
||||
@ -385,6 +391,9 @@ a valid icon in `mkdocs.yml`:
|
||||
|
||||
### Custom admonitions
|
||||
|
||||
[:octicons-file-code-24: Source][Source] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
If you want to add a custom admonition type, all you need is a color and an
|
||||
`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
|
||||
and add the following CSS to an [additional stylesheet]:
|
||||
@ -439,6 +448,7 @@ _Example_:
|
||||
|
||||
``` markdown
|
||||
!!! pied-piper "Pied Piper"
|
||||
|
||||
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.
|
||||
@ -452,6 +462,7 @@ _Result_:
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
[Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
|
||||
[Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
[Custom animations]: icons-emojis.md#with-animations
|
||||
[additional stylesheet]: ../customization.md#additional-css
|
||||
|
||||
@ -10,74 +10,75 @@ useful for documents or landing pages with dedicated _call-to-actions_.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Attribute List
|
||||
|
||||
The [Attribute List][1] 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`
|
||||
This configuration allows to add attributes to all inline- and block-level
|
||||
elements with a simple syntax, turning any link into a button. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
```
|
||||
|
||||
[1]: https://python-markdown.github.io/extensions/attr_list/
|
||||
See additional configuration options:
|
||||
|
||||
- [Attribute Lists]
|
||||
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding buttons
|
||||
|
||||
When the [Attribute List][2] extension is enabled, any clickable element can be
|
||||
converted into a button by adding the `.md-button` CSS class, which will receive
|
||||
the selected [primary color][3].
|
||||
In order to render a link as a button, suffix it with curly braces and add the
|
||||
`#!css .md-button` class selector to it. The button will receive the selected
|
||||
[primary color] and [accent color] if active.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[Subscribe to our mailing list](#){ .md-button }
|
||||
[Don't click me](#){ .md-button }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[Subscribe to our mailing list][4]{ .md-button }
|
||||
[Don't click me][Demo]{ .md-button }
|
||||
|
||||
[2]: #attribute-list
|
||||
[3]: ../setup/changing-the-colors.md#primary-color
|
||||
[4]: javascript:alert$.next("Done!")
|
||||
[primary color]: ../setup/changing-the-colors.md#primary-color
|
||||
[accent color]: ../setup/changing-the-colors.md#accent-color
|
||||
[Demo]: javascript:alert$.next("Hi!")
|
||||
|
||||
### Adding primary buttons
|
||||
|
||||
If you want to display a filled, primary button (like on the [landing page][5]
|
||||
of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
|
||||
CSS classes.
|
||||
If you want to display a filled, primary button (like on the [landing page]
|
||||
of Material for MkDocs), add both, the `#!css .md-button` and
|
||||
`#!css .md-button--primary` CSS class selectors.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[Subscribe to our mailing list](#){ .md-button .md-button--primary }
|
||||
[Don't click me](#){ .md-button .md-button--primary }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[Subscribe to our mailing list][4]{ .md-button .md-button--primary }
|
||||
[Don't click me][Demo]{ .md-button .md-button--primary }
|
||||
|
||||
[5]: ../index.md
|
||||
[landing page]: ../index.md
|
||||
|
||||
### Adding icon buttons
|
||||
|
||||
Of course, icons can be added to both types of buttons by using the [regular
|
||||
icon syntax][6] and referencing a valid path to [any icon bundled with the
|
||||
theme][7].
|
||||
Of course, icons can be added to all types of buttons by using the [icon syntax]
|
||||
together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[Submit :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
|
||||
[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[Submit :fontawesome-solid-paper-plane:][4]{ .md-button .md-button--primary }
|
||||
[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
|
||||
|
||||
[6]: icons-emojis.md#using-icons
|
||||
[7]: icons-emojis.md#search
|
||||
[icon syntax]: icons-emojis.md#using-icons
|
||||
[icon search]: icons-emojis.md#search
|
||||
|
||||
@ -6,191 +6,88 @@ template: overrides/main.html
|
||||
|
||||
Code blocks and examples are an essential part of technical project
|
||||
documentation. Material for MkDocs provides different ways to set up syntax
|
||||
highlighting for code blocks, either during build time using [Pygments][1] or
|
||||
highlighting for code blocks, either during build time using [Pygments] or
|
||||
during runtime using a JavaScript syntax highlighter.
|
||||
|
||||
[1]: https://pygments.org
|
||||
[Pygments]: https://pygments.org
|
||||
|
||||
## Configuration
|
||||
|
||||
### Highlight
|
||||
|
||||
[: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][5],
|
||||
integrates with Material for MkDocs and provides several options for
|
||||
configuring syntax highlighting of code blocks:
|
||||
|
||||
`use_pygments`{ #use-pygments }
|
||||
|
||||
: :octicons-milestone-24: Default: `true` – This option allows to control
|
||||
whether highlighting should be carried out during build time by
|
||||
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
|
||||
necessary [additional stylesheets][6] and [JavaScript][7] if you want to
|
||||
use the latter:
|
||||
|
||||
=== "Pygments"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight
|
||||
- pymdownx.superfences
|
||||
```
|
||||
|
||||
=== "JavaScript"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
use_pygments: false
|
||||
```
|
||||
|
||||
??? example "Syntax highlighting with Highlight.js"
|
||||
|
||||
[Highlight.js][8] can be integrated by creating an [additional
|
||||
JavaScript][7] file initializing the highlighter and including the
|
||||
respective stylesheet and JavaScript from a [CDN][9] serving
|
||||
Highlight.js in `mkdocs.yml`:
|
||||
|
||||
=== "`docs/javascripts/config.js`"
|
||||
|
||||
``` js
|
||||
document$.subscribe(() => {
|
||||
hljs.highlightAll()
|
||||
})
|
||||
```
|
||||
|
||||
=== "`mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
|
||||
- javascripts/config.js
|
||||
extra_css:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
|
||||
```
|
||||
|
||||
Note that Highlight.js has no affiliation with the Highlight extension.
|
||||
|
||||
`linenums`{ #linenums }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – This option will add line numbers
|
||||
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
|
||||
code blocks, consult the section on [adding line numbers][10] later in this
|
||||
document, which also contains some tips on working with line numbers:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
```
|
||||
|
||||
`linenums_style`{ #linenums-style }
|
||||
|
||||
: :octicons-milestone-24: Default: `table` – The Highlight extension provides
|
||||
three ways to add line numbers, all of which are supported by Material for
|
||||
MkDocs. While `table` wraps a code block in a table, `inline` and
|
||||
`pymdownx-inline` render line numbers as part of the line itself:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
linenums_style: pymdownx-inline
|
||||
```
|
||||
|
||||
Note that `inline` will put line numbers next to the actual code, which
|
||||
means that they will be included when selecting text with the cursor or
|
||||
copying a code block to the clipboard. Thus, the usage of `table` or
|
||||
`pymdownx-inline` is recommended.
|
||||
|
||||
_Material for MkDocs doesn't provide official support for the other options of
|
||||
this extension, so they may be supported but might yield unexpected results.
|
||||
Use them at your own risk._
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
|
||||
[4]: https://python-markdown.github.io/extensions/code_hilite/
|
||||
[5]: https://facelessuser.github.io/pymdown-extensions/
|
||||
[6]: ../customization.md#additional-css
|
||||
[7]: ../customization.md#additional-javascript
|
||||
[8]: https://highlightjs.org/
|
||||
[9]: https://cdnjs.com/libraries/highlight.js/
|
||||
[10]: #adding-line-numbers
|
||||
|
||||
### InlineHilite
|
||||
|
||||
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
|
||||
|
||||
The [InlineHilite][11] extension, which is part of [Python Markdown
|
||||
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
|
||||
[Highlight][3] extension and can be enabled via `mkdocs.yml`:
|
||||
This configuration enables syntax highlighting on code blocks and inline code
|
||||
blocks, and allows to include source code directly from other files. Add the
|
||||
following lines to `mkdocs.yml`
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight
|
||||
- pymdownx.inlinehilite
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
### Keys
|
||||
|
||||
[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
|
||||
|
||||
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`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.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/
|
||||
See additional configuration options:
|
||||
|
||||
- [Highlight]
|
||||
- [InlineHilite]
|
||||
- [SuperFences]
|
||||
- [Snippets]
|
||||
|
||||
[Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight
|
||||
[InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite
|
||||
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
|
||||
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
|
||||
|
||||
### Code annotations
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-2.2.0 ... present][Insiders]
|
||||
|
||||
Code annotations offer a comfortable and friendly way to attach arbitrary
|
||||
content to specific sections of code blocks by adding numeric markers in block
|
||||
and inline comments in the language of the block. Add the following to
|
||||
`mkdocs.yml` to enable them globally:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.code.annotate # (1)
|
||||
```
|
||||
|
||||
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
|
||||
text__, images, ... basically anything that can be expressed in Markdown.
|
||||
|
||||
??? info "Enabling code annotations only for specific code blocks"
|
||||
|
||||
If you don't want to enable code annotations globally, because you don't
|
||||
like the automatic inlining behavior, you can enable them for a specific
|
||||
code block by using a slightly different syntax based on the
|
||||
[Attribute List] extension:
|
||||
|
||||
```` yaml
|
||||
``` { .yaml .annotate }
|
||||
# Code block content
|
||||
```
|
||||
````
|
||||
|
||||
Note that the language shortcode which has to come first must now also be
|
||||
prefixed by a `.`.
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[Attribute List]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
|
||||
## Usage
|
||||
|
||||
This section discusses how to use different syntax highlighting features with
|
||||
[Pygments][1] – the default highlighter – so they don't apply when using
|
||||
[Pygments] – the default highlighter – so they don't apply when using
|
||||
a JavaScript syntax highlighter.
|
||||
|
||||
### Specifying the language
|
||||
|
||||
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
|
||||
after the opening block. See the [list of available lexers][17] to find the
|
||||
short name for a given language.
|
||||
To add syntax highlighting to those blocks, add the language shortcode directly
|
||||
after the opening block. See the [list of available lexers] to find the
|
||||
shortcode for a given language.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -206,117 +103,50 @@ _Result_:
|
||||
import tensorflow as tf
|
||||
```
|
||||
|
||||
[17]: https://pygments.org/docs/lexers/
|
||||
[list of available lexers]: https://pygments.org/docs/lexers/
|
||||
|
||||
### Adding annotations
|
||||
|
||||
[:octicons-file-code-24: Source][18] ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][18]{ .mdx-insiders }
|
||||
Code annotations can be placed anywhere in a code block where a comment for the
|
||||
language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
|
||||
`#!js /* ... */`, for Yaml `#!yaml # ...`, etc.[^1]
|
||||
|
||||
Annotations offer a comfortable and friendly way to attach explanations to
|
||||
arbitrary sections of code blocks by adding simple markers within block/inline
|
||||
comments that refer to items of a list following the code block, i.e. `(1)`,
|
||||
`(2)`, etc. Material for MkDocs detaches the list from the flow of the document,
|
||||
injects the content of each list item into a tooltip, and links each list marker
|
||||
to the corresponding tooltip.
|
||||
[^1]:
|
||||
Code annotations require syntax highlighting with [Pygments] – they're
|
||||
currently not compatible with JavaScript syntax highlighters. Support will
|
||||
be added at a later point, allowing to always place code annotations at the
|
||||
end of lines.
|
||||
|
||||
In order to opt-in to annotation support, a slightly different syntax is
|
||||
required – just add the respective [language short code][17] and the `.annotate`
|
||||
class, after the three backticks. Alternatively, if you want to enable annotations
|
||||
globally, add the following to `mkdocs.yml`:
|
||||
_Example_:
|
||||
|
||||
```` markdown
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.code.annotate # (1)
|
||||
```
|
||||
|
||||
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
|
||||
text__, images, ... basically anything that can be expressed in Markdown.
|
||||
````
|
||||
|
||||
_Result_:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.code.annotate
|
||||
- content.code.annotate # (1)
|
||||
```
|
||||
|
||||
Note that annotations can be __placed anywhere__ in a code block where a comment
|
||||
for the language can be placed, which for JavaScript is `// (1)` and
|
||||
`/* (2) */`, for Yaml `# (3)`, etc.
|
||||
|
||||
_Example_:
|
||||
|
||||
```` markdown
|
||||
``` js
|
||||
document$.subscribe(function() { // (1)
|
||||
var tables = document.querySelectorAll(/* (2) */ "article table")
|
||||
tables.forEach(function(table) {
|
||||
new Tablesort(table)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
1. ...
|
||||
2. ...
|
||||
````
|
||||
|
||||
_Result_:
|
||||
|
||||
``` js
|
||||
document$.subscribe(function() { // (1)
|
||||
var tables = document.querySelectorAll(/* (2) */ "article table")
|
||||
tables.forEach(function(table) {
|
||||
new Tablesort(table) // (3)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
1. Annotations can contain __arbitrary content__ which is shown when the marker
|
||||
is focussed, including any kind of formatting, links, admonitions, details,
|
||||
and even diagrams:
|
||||
|
||||
``` mermaid
|
||||
graph LR
|
||||
A[I'm] --> B{a} --> C[diagram];
|
||||
```
|
||||
|
||||
:octicons-light-bulb-16:
|
||||
**Tip:** You can use ++tab++ to navigate annotations.
|
||||
|
||||
2. Annotations can be __placed anywhere__ in a code block were a comment for the
|
||||
underlying language can be placed.
|
||||
|
||||
=== "Python"
|
||||
|
||||
``` python
|
||||
# (1)
|
||||
```
|
||||
|
||||
=== "JavaScript"
|
||||
|
||||
``` js
|
||||
// (2)
|
||||
/* (2) */
|
||||
```
|
||||
|
||||
=== "Lua"
|
||||
|
||||
``` lua
|
||||
-- (3)
|
||||
```
|
||||
|
||||
_We're working on a solution for languages without comments, which will be
|
||||
available shortly._
|
||||
|
||||
1. Of course, this can be combined with [line numbers][10], highlighting and
|
||||
all other code block related features.
|
||||
|
||||
_Annotations require syntax highlighting with [Pygments][26] – they're currently
|
||||
not compatible with other JavaScript-based syntax highlighters. Support may be
|
||||
added later on._
|
||||
|
||||
[18]: ../insiders/index.md
|
||||
[19]: ../assets/screenshots/annotations.png
|
||||
[20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
|
||||
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
|
||||
text__, images, ... basically anything that can be expressed in Markdown.
|
||||
|
||||
### Adding line numbers
|
||||
|
||||
Line numbers can be added to a code block by using the `linenums="<start>"`
|
||||
option directly after the short name, whereas `<start>` represents the starting
|
||||
option directly after the shortcode, whereas `<start>` represents the starting
|
||||
line number. A code block can start from a line number other than `1`, which
|
||||
allows splitting large code blocks for readability.
|
||||
allows to split large code blocks for readability.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -343,60 +173,65 @@ def bubble_sort(items):
|
||||
### Highlighting specific lines
|
||||
|
||||
Specific lines can be highlighted by passing the line numbers to the `hl_lines`
|
||||
argument placed right after the language short name. Note that line counts start
|
||||
at `1`, regardless of the starting line number specified as part of `linenums`.
|
||||
argument placed right after the language shortcode. Note that line counts start
|
||||
at `1`, regardless of the starting line number specified as part of
|
||||
[`linenums`][Adding line numbers].
|
||||
|
||||
_Example_:
|
||||
=== "Line numbers"
|
||||
|
||||
```` markdown
|
||||
``` python hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
````
|
||||
_Example_:
|
||||
|
||||
_Result_:
|
||||
```` markdown
|
||||
``` python hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
````
|
||||
|
||||
``` python hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
_Result_:
|
||||
|
||||
Line ranges can also be used for conveniently specifying multiple lines.
|
||||
``` python hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
|
||||
_Example_:
|
||||
=== "Line ranges"
|
||||
|
||||
```` markdown
|
||||
``` python hl_lines="2-5"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
````
|
||||
_Example_:
|
||||
|
||||
_Result_:
|
||||
```` markdown
|
||||
``` python hl_lines="2-5"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
````
|
||||
|
||||
``` python hl_lines="2-5"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
_Result_:
|
||||
|
||||
``` python hl_lines="2-5"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
if items[j] > items[j + 1]:
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
|
||||
[Adding line numbers]: #adding-line-numbers
|
||||
|
||||
### Highlighting inline code blocks
|
||||
|
||||
When [InlineHilite][21] is enabled, inline code blocks can be highlighted by
|
||||
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
|
||||
the [language short name][17].
|
||||
When [InlineHilite] is enabled, syntax highlighting can be applied to inline
|
||||
code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
|
||||
the corresponding [language shortcode][list of available lexers].
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -408,33 +243,10 @@ _Result_:
|
||||
|
||||
The `#!python range()` function is used to generate a sequence of numbers.
|
||||
|
||||
[21]: #inlinehilite
|
||||
|
||||
### Adding keyboard keys
|
||||
|
||||
When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
Consult the [Python Markdown Extensions][14] documentation to learn about all
|
||||
available key codes.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
++ctrl+alt+del++
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
++ctrl+alt+del++
|
||||
|
||||
[22]: #keys
|
||||
|
||||
### Embedding external files
|
||||
|
||||
_Also known as transcludes or file transclusion in [MultiMarkdown][23]_.
|
||||
|
||||
When [Snippets][24] is enabled, content from other files can be embedded, which
|
||||
is especially useful to reference and embed the contents of source files
|
||||
directly into your project documentation.
|
||||
When [Snippets] is enabled, content from other files can be embedded, which is particularly useful to reference and embed the contents of source files
|
||||
directly in a document without copying.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -450,23 +262,16 @@ _Result_:
|
||||
last 4 years
|
||||
```
|
||||
|
||||
Note that [Snippets][24] is not limited to code blocks, but can be used anywhere
|
||||
from a document to move repeating content to separate files, which is also
|
||||
explained in the [official documentation][16].
|
||||
|
||||
[23]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
|
||||
[24]: #snippets
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom syntax theme
|
||||
|
||||
[:octicons-file-code-24: Source][25] ·
|
||||
[:octicons-file-code-24: Source][Source] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
If [Pygments][26] is used, Material for MkDocs provides the [styles for code
|
||||
blocks][25], which are built with a custom and well-balanced palette that works
|
||||
equally well for both [color schemes][27]:
|
||||
If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
|
||||
[Source], which are built with a custom and well-balanced palette that works
|
||||
equally well for both [color schemes]:
|
||||
|
||||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
|
||||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
|
||||
@ -488,10 +293,8 @@ Code block foreground, background and line highlight colors are defined via:
|
||||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
|
||||
|
||||
Let's say you want to change the color of `#!js "strings"`. While there are
|
||||
several [types of string tokens][28], Material for MkDocs assigns a single color
|
||||
to most of them.
|
||||
|
||||
Create an [additional stylesheet][6], and add:
|
||||
several [types of string tokens], they use the same color. You can assign
|
||||
a new color by using an [additional stylesheet]:
|
||||
|
||||
``` css
|
||||
:root > * {
|
||||
@ -500,7 +303,7 @@ Create an [additional stylesheet][6], and add:
|
||||
```
|
||||
|
||||
If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
|
||||
can lookup the specific class name in the [syntax theme definition][29], and
|
||||
can lookup the specific class name in the [syntax theme definition], and
|
||||
override it as part of your additional stylesheet:
|
||||
|
||||
``` css
|
||||
@ -509,8 +312,8 @@ override it as part of your additional stylesheet:
|
||||
}
|
||||
```
|
||||
|
||||
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
|
||||
[26]: #use-pygments
|
||||
[27]: ../setup/changing-the-colors.md#color-scheme
|
||||
[28]: https://pygments.org/docs/tokens/#literals
|
||||
[29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
|
||||
[Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
|
||||
[color schemes]: ../setup/changing-the-colors.md#color-scheme
|
||||
[types of string tokens]: https://pygments.org/docs/tokens/#literals
|
||||
[additional stylesheet]: ../customization.md#additional-css
|
||||
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
|
||||
|
||||
@ -93,6 +93,24 @@ markdown_extensions:
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
||||
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
|
||||
|
||||
### Adding keyboard keys
|
||||
|
||||
When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
Consult the [Python Markdown Extensions][14] documentation to learn about all
|
||||
available key codes.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
++ctrl+alt+del++
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
++ctrl+alt+del++
|
||||
|
||||
[22]: #keys
|
||||
|
||||
### SmartSymbols
|
||||
|
||||
The [SmartSymbols][9] extension, which is also part of [Python Markdown
|
||||
|
||||
@ -79,9 +79,9 @@ your documentation project.
|
||||
|
||||
### Minimal configuration
|
||||
|
||||
The minimal configuration is a good starting point for when you're using
|
||||
Material for MkDocs for the first time. The best idea is to explore the
|
||||
[reference], and gradually add what you want to use:
|
||||
This configuration is a good starting point for when you're using Material for
|
||||
MkDocs for the first time. The best idea is to explore the [reference], and
|
||||
gradually add what you want to use:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -100,8 +100,8 @@ markdown_extensions:
|
||||
|
||||
### Recommended configuration
|
||||
|
||||
The recommended configuration enables all Markdown-related features of Material
|
||||
for MkDocs and is great for bootstrapping a new documentation project:
|
||||
This configuration enables all Markdown-related features of Material for MkDocs
|
||||
and is great for experienced users bootstrapping a new documentation project:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
@ -248,7 +248,7 @@ The following configuration options are supported:
|
||||
: :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][Pymdownx slug]:
|
||||
like for example those from [Python Markdown Extensions][Slugs]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
@ -295,7 +295,7 @@ own risk.
|
||||
|
||||
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
|
||||
[Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Pymdownx slug]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
|
||||
### Tables
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user