mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
---
|
||
template: overrides/main.html
|
||
---
|
||
|
||
# Code blocks
|
||
|
||
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] or
|
||
during runtime using a JavaScript syntax highlighter.
|
||
|
||
[Pygments]: https://pygments.org
|
||
|
||
## Configuration
|
||
|
||
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:
|
||
anchor_linenums: true
|
||
- pymdownx.inlinehilite
|
||
- pymdownx.snippets
|
||
- pymdownx.superfences
|
||
```
|
||
|
||
The following sections discuss how to use different syntax highlighting features
|
||
with [Pygments], the recommended highlighter, so they don't apply when using a
|
||
JavaScript syntax highlighter.
|
||
|
||
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-tag-24: 8.0.0][Code annotations support] ·
|
||
:octicons-unlock-24: Feature flag ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
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 code 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 for a specific code block"
|
||
|
||
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 Lists] extension:
|
||
|
||
```` yaml
|
||
``` { .yaml .annotate }
|
||
# Code block content
|
||
```
|
||
````
|
||
|
||
Note that the language shortcode which has to come first must now also be
|
||
prefixed by a `.`.
|
||
|
||
[Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
|
||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||
|
||
#### Anchor links
|
||
|
||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||
[:octicons-tag-24: insiders-4.4.0][Insiders] ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
In order to link to code annotations and share them more easily, [Insiders] adds
|
||
an anchor link to each annotation automatically, which you can copy via right
|
||
click or open in a new tab:
|
||
|
||
``` yaml
|
||
# (1)!
|
||
```
|
||
|
||
1. If you ++cmd++ :material-plus::material-cursor-default-outline: me, I'm
|
||
rendered open in a new tab. You can also right-click me to __copy link
|
||
address__ to share me with others.
|
||
|
||
[Insiders]: ../insiders/index.md
|
||
|
||
## Usage
|
||
|
||
Code blocks must be enclosed with two separate lines containing three backticks.
|
||
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_:
|
||
|
||
```` markdown
|
||
``` py
|
||
import tensorflow as tf
|
||
```
|
||
````
|
||
|
||
_Result_:
|
||
|
||
``` py
|
||
import tensorflow as tf
|
||
```
|
||
|
||
[list of available lexers]: https://pygments.org/docs/lexers/
|
||
|
||
### Adding a title
|
||
|
||
[:octicons-tag-24: 7.3.6][Title support] ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
In order to provide additional context, a custom title can be added to a code
|
||
block by using the `title="<custom title>"` option directly after the shortcode,
|
||
e.g. to display the name of a file:
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` py title="bubble_sort.py"
|
||
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_:
|
||
|
||
``` py title="bubble_sort.py"
|
||
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]
|
||
```
|
||
|
||
[Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6
|
||
|
||
### Adding annotations
|
||
|
||
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 in `#!yaml # ...`, etc.[^1]
|
||
|
||
[^1]:
|
||
Code annotations require syntax highlighting with [Pygments] – they're
|
||
currently not compatible with JavaScript syntax highlighters, or languages
|
||
that do not have comments in their grammar. However, we're actively working
|
||
on supporting alternate ways of defining code annotations, allowing to
|
||
always place code annotations at the end of lines.
|
||
|
||
_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 # (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.
|
||
|
||
#### Stripping comments
|
||
|
||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||
[:octicons-tag-24: insiders-4.4.0][Insiders] ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
If you wish to strip the comment characters surrounding a code annotation,
|
||
[Insiders] adds a new syntax that allows for just that. Simply add an `!` after
|
||
the closing parens of the code annotation:
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` yaml
|
||
# (1)!
|
||
```
|
||
|
||
1. Look ma, less line noise!
|
||
````
|
||
|
||
_Result_:
|
||
|
||
``` yaml
|
||
# (1)!
|
||
```
|
||
|
||
1. Look ma, less line noise!
|
||
|
||
Note that this only allows for a single code annotation to be rendered per
|
||
comment. If you want to add multiple code annotations, comments cannot be
|
||
stripped for technical reasons.
|
||
|
||
### Adding line numbers
|
||
|
||
Line numbers can be added to a code block by using the `linenums="<start>"`
|
||
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 to split large code blocks for readability.
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` py linenums="1"
|
||
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_:
|
||
|
||
``` py linenums="1"
|
||
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]
|
||
```
|
||
|
||
### Highlighting specific lines
|
||
|
||
Specific lines can be highlighted by passing the line numbers to the `hl_lines`
|
||
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].
|
||
|
||
=== "Line numbers"
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` py 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_:
|
||
|
||
``` py linenums="1" 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]
|
||
```
|
||
|
||
=== "Line number ranges"
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` py 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_:
|
||
|
||
``` py linenums="1" 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] 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_:
|
||
|
||
``` markdown
|
||
The `#!python range()` function is used to generate a sequence of numbers.
|
||
```
|
||
|
||
_Result_:
|
||
|
||
The `#!python range()` function is used to generate a sequence of numbers.
|
||
|
||
### Embedding external files
|
||
|
||
When [Snippets] is enabled, content from other files (including source files)
|
||
can be embedded by using the [`--8<--` notation][Snippets notation] directly
|
||
from within a code block:
|
||
|
||
_Example_:
|
||
|
||
```` markdown
|
||
``` title=".browserslistrc"
|
||
--8<-- ".browserslistrc"
|
||
```
|
||
````
|
||
|
||
_Result_:
|
||
|
||
``` title=".browserslistrc"
|
||
last 4 years
|
||
```
|
||
|
||
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
|
||
|
||
## Customization
|
||
|
||
### Custom syntax theme
|
||
|
||
If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
|
||
[colors], 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`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
|
||
|
||
Code block foreground, background and line highlight colors are defined via:
|
||
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
|
||
- :material-checkbox-blank-circle:{ style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
|
||
- :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], they use the same color. You can assign
|
||
a new color by using an [additional style sheet]:
|
||
|
||
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
|
||
|
||
``` css
|
||
:root > * {
|
||
--md-code-hl-string-color: #0FF1CE;
|
||
}
|
||
```
|
||
|
||
=== ":octicons-file-code-16: mkdocs.yml"
|
||
|
||
``` yaml
|
||
extra_css:
|
||
- stylesheets/extra.css
|
||
```
|
||
|
||
If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
|
||
can lookup the specific CSS class name in the [syntax theme definition], and
|
||
override it as part of your [additional style sheet]:
|
||
|
||
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
|
||
|
||
``` css
|
||
.highlight .sb {
|
||
color: #0FF1CE;
|
||
}
|
||
```
|
||
|
||
=== ":octicons-file-code-16: mkdocs.yml"
|
||
|
||
``` yaml
|
||
extra_css:
|
||
- stylesheets/extra.css
|
||
```
|
||
|
||
[colors]: 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 style sheet]: ../customization.md#additional-css
|
||
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
|
||
|
||
### Annotations with numbers
|
||
|
||
Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
|
||
were rendered with markers showing the original number as used by the author.
|
||
However, for technical reasons code annotation numbers restart each code block,
|
||
which might lead to confusion. For this reason, code annotations now render as
|
||
`+` signs which are rotated if they're open to denote that clicking them again
|
||
will close them.
|
||
|
||
If you wish to revert to the prior behavior and display code annotation numbers,
|
||
you can add an [additional style sheet] and copy and paste the following CSS:
|
||
|
||
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
|
||
|
||
``` css
|
||
.md-typeset .md-annotation__index > ::before {
|
||
content: attr(data-md-annotation-id);
|
||
}
|
||
.md-typeset :focus-within > .md-annotation__index > ::before {
|
||
transform: none;
|
||
}
|
||
```
|
||
|
||
=== ":octicons-file-code-16: mkdocs.yml"
|
||
|
||
``` yaml
|
||
extra_css:
|
||
- stylesheets/extra.css
|
||
```
|
||
|
||
[code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
|