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

Updated code block reference

Browse Source
This commit is contained in:
squidfunk 2021-10-03 18:02:59 +02:00
parent b8becde3bb
commit df88640208
8 changed files with 248 additions and 426 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/insiders/index.md
View File

@ -150,7 +150,7 @@ The following features are currently exclusively available to sponsors:
- [x] [Stay on page when switching versions][28] - [x] [Stay on page when switching versions][28]
- [x] [Version warning][26] - [x] [Version warning][26]
- [x] [Custom admonition icons][31] - [x] [Custom admonition icons][31]
- [x] [Code block annotations][25] - [x] [Code annotations][25]
- [x] [Anchor tracking ][24] - [x] [Anchor tracking ][24]
- [x] [Mermaid.js integration][27] - [x] [Mermaid.js integration][27]
@ -173,7 +173,7 @@ the public for general availability.
#### $ 4,000 – Ghost Pepper #### $ 4,000 – Ghost Pepper
- [x] [Anchor tracking][24] - [x] [Anchor tracking][24]
- [x] [Code block annotations][25] - [x] [Code annotations][25]
- [x] [Version warning][26] - [x] [Version warning][26]
[24]: ../setup/setting-up-navigation.md#anchor-tracking [24]: ../setup/setting-up-navigation.md#anchor-tracking

63
docs/reference/abbreviations.md
View File

@ -11,43 +11,31 @@ enable site-wide glossaries.
## Configuration ## Configuration
### Abbreviations This configuration enables abbreviations, and allows to build a simple
project-wide glossary sourcing definitions from a central location. Add the
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] following line to `mkdocs.yml`:
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:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- abbr - 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 - pymdownx.snippets
``` ```
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ See additional configuration options:
[4]: https://facelessuser.github.io/pymdown-extensions/
- [Abbreviations]
- [Snippets]
[Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
## Usage ## Usage
### Adding abbreviations ### Adding abbreviations
When the [Abbreviations][5] extension is enabled, abbreviations can be defined Abbreviations can be defined by using a special syntax similar to URLs and
with a special syntax similar to URLs and [footnotes][6] at any point in the [footnotes], starting with a `*` and immediately followed by the term or
Markdown document. acronym to be associated in square brackets.
_Example_: _Example_:
@ -65,18 +53,23 @@ The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language *[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium *[W3C]: World Wide Web Consortium
[5]: #abbreviations_1 [footnotes]: footnotes.md
[6]: footnotes.md
### Adding a glossary ### Adding a glossary
When [Snippets][7] is enabled, content from other files can be embedded, which The [Snippets] extension can be used to implement a simple glossary, by moving
is especially useful to include abbreviations from a central file – a glossary – all abbreviations in a dedicated file[^1] and include it with the
and embed them into any other file. [`--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_: _Example_:
=== "`docs/page.md`" === ":octicons-file-code-16: docs/page.md"
```` markdown ```` markdown
The HTML specification is maintained by the W3C. The HTML specification is maintained by the W3C.
@ -84,7 +77,7 @@ _Example_:
--8<-- "includes/abbreviations.md" --8<-- "includes/abbreviations.md"
```` ````
=== "`includes/abbreviations.md`" === ":octicons-file-code-16: includes/abbreviations.md"
```` markdown ```` markdown
*[HTML]: Hyper Text Markup Language *[HTML]: Hyper Text Markup Language
@ -95,8 +88,4 @@ _Result_:
The HTML specification is maintained by the W3C. The HTML specification is maintained by the W3C.
_Remember to locate the Markdown file containing the definitions outside of the_ [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
unreferenced file._
[7]: #snippets

25
docs/reference/admonitions.md
View File

@ -11,9 +11,9 @@ inclusion and nesting of arbitrary content.
## Configuration ## Configuration
The following configuration enables admonitions, allows to make them collapsible This configuration enables admonitions, allows to make them collapsible and to
and to nest arbitrary content inside admonition bodies. Add the following lines nest arbitrary content inside admonition bodies. Add the following lines to
to `mkdocs.yml`: `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -111,9 +111,9 @@ _Result_:
### Collapsible blocks ### Collapsible blocks
If the [Details] extension is enabled and an admonition is started with `???` When [Details] is enabled and an admonition block is started with `???` instead
instead of `!!!`, the admonition is rendered as a collapsible block with a of `!!!`, the admonition is rendered as a collapsible block with a small toggle
small marker on the right side. on the right side.
_Example_: _Example_:
@ -155,6 +155,9 @@ _Result_:
### Inline blocks ### 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 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 them to the right using the `inline` + `end` modifiers, or to the left using
only the `inline` modifier. 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 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. 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 ### Supported types
Following is a list of type qualifiers provided by Material for MkDocs, whereas 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 ### 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 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 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 ### 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 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 `*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
and add the following CSS to an [additional stylesheet]: and add the following CSS to an [additional stylesheet]:
@ -439,6 +448,7 @@ _Example_:
``` markdown ``` markdown
!!! pied-piper "Pied Piper" !!! pied-piper "Pied Piper"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
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.
@ -452,6 +462,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.
[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 icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[Custom animations]: icons-emojis.md#with-animations [Custom animations]: icons-emojis.md#with-animations
[additional stylesheet]: ../customization.md#additional-css [additional stylesheet]: ../customization.md#additional-css

55
docs/reference/buttons.md
View File

@ -10,74 +10,75 @@ useful for documents or landing pages with dedicated _call-to-actions_.
## Configuration ## Configuration
### Attribute List 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
The [Attribute List][1] extension, which is part of the standard Markdown following lines to `mkdocs.yml`:
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- attr_list - 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 ## Usage
### Adding buttons ### Adding buttons
When the [Attribute List][2] extension is enabled, any clickable element can be In order to render a link as a button, suffix it with curly braces and add the
converted into a button by adding the `.md-button` CSS class, which will receive `#!css .md-button` class selector to it. The button will receive the selected
the selected [primary color][3]. [primary color] and [accent color] if active.
_Example_: _Example_:
``` markdown ``` markdown
[Subscribe to our mailing list](#){ .md-button } [Don't click me](#){ .md-button }
``` ```
_Result_: _Result_:
[Subscribe to our mailing list][4]{ .md-button } [Don't click me][Demo]{ .md-button }
[2]: #attribute-list [primary color]: ../setup/changing-the-colors.md#primary-color
[3]: ../setup/changing-the-colors.md#primary-color [accent color]: ../setup/changing-the-colors.md#accent-color
[4]: javascript:alert$.next("Done!") [Demo]: javascript:alert$.next("Hi!")
### Adding primary buttons ### Adding primary buttons
If you want to display a filled, primary button (like on the [landing page][5] If you want to display a filled, primary button (like on the [landing page]
of Material for MkDocs), add both the `.md-button` and `.md-button--primary` of Material for MkDocs), add both, the `#!css .md-button` and
CSS classes. `#!css .md-button--primary` CSS class selectors.
_Example_: _Example_:
``` markdown ``` markdown
[Subscribe to our mailing list](#){ .md-button .md-button--primary } [Don't click me](#){ .md-button .md-button--primary }
``` ```
_Result_: _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 ### Adding icon buttons
Of course, icons can be added to both types of buttons by using the [regular Of course, icons can be added to all types of buttons by using the [icon syntax]
icon syntax][6] and referencing a valid path to [any icon bundled with the together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
theme][7].
_Example_: _Example_:
``` markdown ``` markdown
[Submit :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary } [Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
``` ```
_Result_: _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 [icon syntax]: icons-emojis.md#using-icons
[7]: icons-emojis.md#search [icon search]: icons-emojis.md#search

495
docs/reference/code-blocks.md
View File

@ -6,191 +6,88 @@ template: overrides/main.html
Code blocks and examples are an essential part of technical project Code blocks and examples are an essential part of technical project
documentation. Material for MkDocs provides different ways to set up syntax 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. during runtime using a JavaScript syntax highlighter.
[1]: https://pygments.org [Pygments]: https://pygments.org
## Configuration ## Configuration
### Highlight This configuration enables syntax highlighting on code blocks and inline code
blocks, and allows to include source code directly from other files. Add the
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] · following lines to `mkdocs.yml`
: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`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- pymdownx.highlight
- pymdownx.inlinehilite - 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 - 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 - 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 ## Usage
This section discusses how to use different syntax highlighting features with 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. a JavaScript syntax highlighter.
### Specifying the language ### Specifying the language
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 syntax highlighting to those blocks, add the language shortcode directly
after the opening block. See the [list of available lexers][17] to find the after the opening block. See the [list of available lexers] to find the
short name for a given language. shortcode for a given language.
_Example_: _Example_:
@ -206,117 +103,50 @@ _Result_:
import tensorflow as tf import tensorflow as tf
``` ```
[17]: https://pygments.org/docs/lexers/ [list of available lexers]: https://pygments.org/docs/lexers/
### Adding annotations ### Adding annotations
[:octicons-file-code-24: Source][18] · Code annotations can be placed anywhere in a code block where a comment for the
:octicons-beaker-24: Experimental · language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][18]{ .mdx-insiders } `#!js /* ... */`, for Yaml `#!yaml # ...`, etc.[^1]
Annotations offer a comfortable and friendly way to attach explanations to [^1]:
arbitrary sections of code blocks by adding simple markers within block/inline Code annotations require syntax highlighting with [Pygments] – they're
comments that refer to items of a list following the code block, i.e. `(1)`, currently not compatible with JavaScript syntax highlighters. Support will
`(2)`, etc. Material for MkDocs detaches the list from the flow of the document, be added at a later point, allowing to always place code annotations at the
injects the content of each list item into a tooltip, and links each list marker end of lines.
to the corresponding tooltip.
In order to opt-in to annotation support, a slightly different syntax is _Example_:
required – just add the respective [language short code][17] and the `.annotate`
class, after the three backticks. Alternatively, if you want to enable annotations ```` markdown
globally, add the following to `mkdocs.yml`: ``` 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 ``` yaml
theme: theme:
features: features:
- content.code.annotate - content.code.annotate # (1)
``` ```
Note that annotations can be __placed anywhere__ in a code block where a comment 1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
for the language can be placed, which for JavaScript is `// (1)` and text__, images, ... basically anything that can be expressed in Markdown.
`/* (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
### Adding line numbers ### Adding line numbers
Line numbers can be added to a code block by using the `linenums="<start>"` 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 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_: _Example_:
@ -343,60 +173,65 @@ def bubble_sort(items):
### Highlighting specific lines ### Highlighting specific lines
Specific lines can be highlighted by passing the line numbers to the `hl_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 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`. at `1`, regardless of the starting line number specified as part of
[`linenums`][Adding line numbers].
_Example_: === "Line numbers"
```` markdown _Example_:
``` 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_: ```` 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" _Result_:
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 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 _Example_:
``` 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_: ```` 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" _Result_:
def bubble_sort(items):
for i in range(len(items)): ``` python hl_lines="2-5"
for j in range(len(items) - 1 - i): def bubble_sort(items):
if items[j] > items[j + 1]: for i in range(len(items)):
items[j], items[j + 1] = items[j + 1], items[j] 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 ### Highlighting inline code blocks
When [InlineHilite][21] is enabled, inline code blocks can be highlighted by When [InlineHilite] is enabled, syntax highlighting can be applied to inline
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
the [language short name][17]. the corresponding [language shortcode][list of available lexers].
_Example_: _Example_:
@ -408,33 +243,10 @@ _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.
[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 ### Embedding external files
_Also known as transcludes or file transclusion in [MultiMarkdown][23]_. 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.
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.
_Example_: _Example_:
@ -450,23 +262,16 @@ _Result_:
last 4 years 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 ## Customization
### Custom syntax theme ### Custom syntax theme
[:octicons-file-code-24: Source][25] · [:octicons-file-code-24: Source][Source] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
If [Pygments][26] is used, Material for MkDocs provides the [styles for code If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
blocks][25], which are built with a custom and well-balanced palette that works [Source], which are built with a custom and well-balanced palette that works
equally well for both [color schemes][27]: 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-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-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` - :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 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 several [types of string tokens], they use the same color. You can assign
to most of them. a new color by using an [additional stylesheet]:
Create an [additional stylesheet][6], and add:
``` css ``` css
:root > * { :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 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: override it as part of your additional stylesheet:
``` css ``` 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# [Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[26]: #use-pygments [color schemes]: ../setup/changing-the-colors.md#color-scheme
[27]: ../setup/changing-the-colors.md#color-scheme [types of string tokens]: https://pygments.org/docs/tokens/#literals
[28]: https://pygments.org/docs/tokens/#literals [additional stylesheet]: ../customization.md#additional-css
[29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss

18
docs/reference/formatting.md
View File

@ -93,6 +93,24 @@ markdown_extensions:
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ [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 ### SmartSymbols
The [SmartSymbols][9] extension, which is also part of [Python Markdown The [SmartSymbols][9] extension, which is also part of [Python Markdown

10
docs/setup/extensions/index.md
View File

@ -79,9 +79,9 @@ your documentation project.
### Minimal configuration ### Minimal configuration
The minimal configuration is a good starting point for when you're using This configuration is a good starting point for when you're using Material for
Material for MkDocs for the first time. The best idea is to explore the MkDocs for the first time. The best idea is to explore the [reference], and
[reference], and gradually add what you want to use: gradually add what you want to use:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -100,8 +100,8 @@ markdown_extensions:
### Recommended configuration ### Recommended configuration
The recommended configuration enables all Markdown-related features of Material This configuration enables all Markdown-related features of Material for MkDocs
for MkDocs and is great for bootstrapping a new documentation project: and is great for experienced users bootstrapping a new documentation project:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:

4
docs/setup/extensions/python-markdown.md
View File

@ -248,7 +248,7 @@ The following configuration options are supported:
: :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][Pymdownx slug]: like for example those from [Python Markdown Extensions][Slugs]:
=== "Unicode" === "Unicode"
@ -295,7 +295,7 @@ own risk.
[Table of Contents]: https://python-markdown.github.io/extensions/toc/ [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 [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 ### Tables