mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Documentation
This commit is contained in:
squidfunk
parent
71926399c4
commit
0676ae1f4b
@ -112,6 +112,7 @@ The following features are currently exclusively available to sponsors:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
|
||||
- [x] [Code block annotations :material-new-box:][24]
|
||||
- [x] [Anchor tracking :material-new-box:][23]
|
||||
- [x] [Section index pages][21]
|
||||
- [x] [Latest release tag][15]
|
||||
@ -171,18 +172,19 @@ the public for general availability.
|
||||
#### $ 4,000 – Ghost Pepper
|
||||
|
||||
- [x] [Anchor tracking][23]
|
||||
- [ ] Code block annotations
|
||||
- [x] [Code block annotations][24]
|
||||
- [ ] Back-to-top button
|
||||
|
||||
[23]: setup/setting-up-navigation.md#anchor-tracking
|
||||
[24]: reference/code-blocks.md#adding-annotations
|
||||
|
||||
#### $ 5,000 – Aji Panca
|
||||
|
||||
- [x] [Mermaid.js integration][24]
|
||||
- [x] [Mermaid.js integration][25]
|
||||
- [ ] List of last searches
|
||||
- [ ] Advanced routing for versioning
|
||||
|
||||
[24]: reference/diagrams.md
|
||||
[25]: reference/diagrams.md
|
||||
|
||||
#### $ 6,000 – Trinidad Scorpion
|
||||
|
||||
@ -198,10 +200,10 @@ the public for general availability.
|
||||
|
||||
#### Future
|
||||
|
||||
- [ ] [Material for MkDocs Live Edit][25]
|
||||
- [ ] [Material for MkDocs Live Edit][26]
|
||||
- [ ] New layouts and styles
|
||||
|
||||
[25]: https://twitter.com/squidfunk/status/1338252230265360391
|
||||
[26]: https://twitter.com/squidfunk/status/1338252230265360391
|
||||
|
||||
### Goals completed
|
||||
|
||||
@ -247,10 +249,10 @@ implemented behind feature flags; all configuration changes are
|
||||
backward-compatible. This means that your users will be able to build the
|
||||
documentation locally with Material for MkDocs and when they push their changes,
|
||||
it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
|
||||
recommended to [install Insiders][26] only in CI, as you don't want to expose
|
||||
recommended to [install Insiders][27] only in CI, as you don't want to expose
|
||||
your `GH_TOKEN` to users.
|
||||
|
||||
[26]: publishing-your-site.md#github-pages
|
||||
[27]: publishing-your-site.md#github-pages
|
||||
|
||||
### Terms
|
||||
|
||||
@ -259,7 +261,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
|
||||
|
||||
Yes. Whether you're an individual or a company, you may use _Material for MkDocs
|
||||
Insiders_ precisely under the same terms as Material for MkDocs, which are given
|
||||
by the [MIT license][27]. However, we kindly ask you to respect the following
|
||||
by the [MIT license][28]. However, we kindly ask you to respect the following
|
||||
guidelines:
|
||||
|
||||
- Please __don't distribute the source code__ of Insiders. You may freely use
|
||||
@ -270,7 +272,7 @@ guidelines:
|
||||
- If you cancel your subscription, you're removed as a collaborator and will
|
||||
miss out on future updates of Insiders. However, you may __use the latest
|
||||
version__ that's available to you __as long as you like__. Just remember that
|
||||
[GitHub deletes private forks][28].
|
||||
[GitHub deletes private forks][29].
|
||||
|
||||
[27]: license.md
|
||||
[28]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
|
||||
[28]: license.md
|
||||
[29]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
|
||||
|
||||
@ -206,6 +206,61 @@ import tensorflow as tf
|
||||
|
||||
[17]: 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 }
|
||||
|
||||
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 removes 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.
|
||||
|
||||
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.
|
||||
|
||||
_Example_:
|
||||
|
||||
```` markdown
|
||||
``` {: .js .annotate }
|
||||
document$.subscribe(function() { // (1)
|
||||
var tables = document.querySelectorAll(/* (2) */ "article table")
|
||||
tables.forEach(function(table) {
|
||||
new Tablesort(table)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
1. ...
|
||||
2. ...
|
||||
````
|
||||
|
||||
_Result_:
|
||||
|
||||
<figure markdown="1">
|
||||
|
||||
[![Annotations][19]][19]
|
||||
|
||||
<figcaption markdown="1">
|
||||
|
||||
A demo is worth a thousand words — check it out at
|
||||
[squidfunk.github.io/mkdocs-material-insiders][20]
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
_Annotations require syntax highlighting with [Pygments][24] – they're currently
|
||||
not compatible with other JavaScript-based syntax highlighters. Support may be
|
||||
added later on._
|
||||
|
||||
[18]: ../insiders.md
|
||||
[19]: ../assets/screenshots/annotations.png
|
||||
[20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
|
||||
|
||||
### Adding line numbers
|
||||
|
||||
Line numbers can be added to a code block by using the `linenums="<start>"`
|
||||
@ -265,7 +320,7 @@ def bubble_sort(items):
|
||||
|
||||
### Highlighting inline code blocks
|
||||
|
||||
When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
|
||||
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].
|
||||
|
||||
@ -279,11 +334,11 @@ _Result_:
|
||||
|
||||
The `#!python range()` function is used to generate a sequence of numbers.
|
||||
|
||||
[18]: #inlinehilite
|
||||
[21]: #inlinehilite
|
||||
|
||||
### Adding keyboard keys
|
||||
|
||||
When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
Consult the [Python Markdown Extensions][16] documentation to learn about all
|
||||
available key codes.
|
||||
|
||||
@ -297,13 +352,13 @@ _Result_:
|
||||
|
||||
++ctrl+alt+del++
|
||||
|
||||
[19]: #keys
|
||||
[22]: #keys
|
||||
|
||||
### Embedding external files
|
||||
|
||||
_Also known as transcludes or file transclusion in [MultiMarkdown][20]_.
|
||||
_Also known as transcludes or file transclusion in [MultiMarkdown][23]_.
|
||||
|
||||
When [Snippets][21] is enabled, content from other files can be embedded, which
|
||||
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.
|
||||
|
||||
@ -321,23 +376,23 @@ _Result_:
|
||||
last 4 years
|
||||
```
|
||||
|
||||
Note that [Snippets][21] is not limited to code blocks, but can be used anywhere
|
||||
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].
|
||||
|
||||
[20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
|
||||
[21]: #snippets
|
||||
[23]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
|
||||
[24]: #snippets
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom syntax theme
|
||||
|
||||
[:octicons-file-code-24: Source][22] ·
|
||||
[:octicons-file-code-24: Source][25] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
If [Pygments][23] is used, Material for MkDocs provides the [styles for code
|
||||
blocks][22], which are built with a custom and well-balanced palette that works
|
||||
equally well for both [color schemes][24]:
|
||||
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]:
|
||||
|
||||
- :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`
|
||||
@ -359,7 +414,7 @@ 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][25], Material for MkDocs assigns a single color
|
||||
several [types of string tokens][28], Material for MkDocs assigns a single color
|
||||
to most of them.
|
||||
|
||||
Create an [additional stylesheet][6], and add:
|
||||
@ -371,7 +426,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][26], and
|
||||
can lookup the specific class name in the [syntax theme definition][29], and
|
||||
override it as part of your additional stylesheet:
|
||||
|
||||
``` css
|
||||
@ -380,8 +435,8 @@ override it as part of your additional stylesheet:
|
||||
}
|
||||
```
|
||||
|
||||
[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
|
||||
[23]: #use-pygments
|
||||
[24]: ../setup/changing-the-colors.md#color-scheme
|
||||
[25]: https://pygments.org/docs/tokens/#literals
|
||||
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss
|
||||
[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/markdown/_codehilite.scss
|
||||
|
||||
Loading…
Reference in New Issue
Block a user