starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-07-22 05:53:03 -04:00
Code Issues Packages Projects Releases Wiki Activity

Restructured documentation (#5692)

Browse Source
This commit is contained in:
Martin Donath
2023-09-14 19:09:18 +02:00
committed by GitHub
parent 19437db8fc
commit cd008fdf29
83 changed files with 6877 additions and 3354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -13,8 +13,8 @@ during runtime using a JavaScript syntax highlighter.
## 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
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
@@ -46,8 +46,8 @@ See additional configuration options:
### Code copy button
[:octicons-tag-24: 9.0.0][Code copy button support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 9.0.0 -->
<!-- md:feature -->
Code blocks can automatically render a button on the right side to allow the
user to copy a code block's contents to the clipboard. Add the following to
@@ -59,8 +59,6 @@ theme:
- content.code.copy
```
[Code copy button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
??? info "Enabling or disabling code copy buttons for a specific code block"
If you don't want to enable code copy buttons globally, you can enable them
@@ -73,7 +71,7 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the copy button can also be disabled for a
specific code block:
@@ -85,9 +83,9 @@ theme:
### Code selection button
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.32.0 -->
<!-- md:flag experimental -->
Code blocks can include a button to allow for the selection of line ranges by
the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
@@ -101,8 +99,8 @@ theme:
??? info "Enabling or disabling code selection buttons for a specific code block"
If you don't want to enable code selection buttons globally, you can enable
them for a specific code block by using a slightly different syntax based on
If you don't want to enable code selection buttons globally, you can enable
them for a specific code block by using a slightly different syntax based on
the [Attribute Lists] extension:
```` yaml
@@ -111,7 +109,7 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the selection button can also be disabled for
a specific code block:
@@ -121,13 +119,12 @@ theme:
```
````
[Insiders]: ../insiders/index.md
[line highlighting]: #highlighting-specific-lines
### Code annotations
[:octicons-tag-24: 8.0.0][Code annotations support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 8.0.0 -->
<!-- md:feature -->
Code annotations offer a comfortable and friendly way to attach arbitrary
content to specific sections of code blocks by adding numeric markers in block
@@ -156,21 +153,20 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
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
#### Custom selectors
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.32.0 -->
<!-- md:flag experimental -->
Normally, code annotations can only be [placed in comments], as comments can be
considered safe for placement. However, sometimes it might be necessary to place
annotations in parts of the code block where comments are not allowed, e.g. in
annotations in parts of the code block where comments are not allowed, e.g. in
strings.
Additional selectors can be set per-language:
@@ -292,8 +288,8 @@ theme:
#### Stripping comments
[:octicons-tag-24: 8.5.0][Stripping comments support] ·
:octicons-beaker-24: Experimental
<!-- md:version 8.5.0 -->
<!-- md:flag experimental -->
If you wish to strip the comment characters surrounding a code annotation,
simply add an `!` after the closing parenthesis of the code annotation:
@@ -320,8 +316,6 @@ 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.
[Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
### Adding line numbers
Line numbers can be added to a code block by using the `linenums="<start>"`
@@ -552,12 +546,11 @@ This will render annotations with a larger width:
### 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.
Prior to <!-- md:version 8.1.0 -->, 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:
@@ -579,5 +572,3 @@ you can add an [additional style sheet] and copy and paste the following CSS:
extra_css:
- stylesheets/extra.css
```
[code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0