mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-28 01:10:58 +01:00
Added docs on extended formatting
This commit is contained in:
squidfunk
parent
807fbdb1bc
commit
04bacbd101
@ -336,18 +336,18 @@ If [Pygments][22] is used, Material for MkDocs provides the [styles for code
|
||||
blocks][21], which are built with a custom and well-balanced palette that works
|
||||
equally well for both [color schemes][23]:
|
||||
|
||||
- :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`
|
||||
* :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`
|
||||
|
||||
Let's say you want to change the color of `#!js "strings"`. While there are
|
||||
several [types of string tokens][24], Material for MkDocs assigns a single color
|
||||
|
||||
@ -108,9 +108,9 @@ _Example_:
|
||||
```
|
||||
=== "Unordered list"
|
||||
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
|
||||
=== "Ordered list"
|
||||
|
||||
@ -123,9 +123,9 @@ _Result_:
|
||||
|
||||
=== "Unordered list"
|
||||
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
|
||||
=== "Ordered list"
|
||||
|
||||
@ -149,16 +149,16 @@ _Example_:
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
|
||||
=== "Ordered List"
|
||||
|
||||
@ -186,16 +186,16 @@ _Result_:
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
- Sed sagittis eleifend rutrum
|
||||
- Donec vitae suscipit est
|
||||
- Nulla tempor lobortis orci
|
||||
* Sed sagittis eleifend rutrum
|
||||
* Donec vitae suscipit est
|
||||
* Nulla tempor lobortis orci
|
||||
|
||||
=== "Ordered List"
|
||||
|
||||
|
||||
189
docs/reference/formatting.md
Normal file
189
docs/reference/formatting.md
Normal file
@ -0,0 +1,189 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Formatting
|
||||
|
||||
Material for MkDocs provides support for several HTML elements that can be used
|
||||
to highlight sections of a document or apply specific formatting. Additionally,
|
||||
[Critic Markup][1] is supported, adding the ability to display suggested changes
|
||||
for a document.
|
||||
|
||||
[1]: http://criticmarkup.com/
|
||||
|
||||
## Configuration
|
||||
|
||||
### Critic
|
||||
|
||||
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
|
||||
|
||||
The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
|
||||
allows for the __usage of [Critic Markup][1] to highlight changes__ in a
|
||||
document, and can be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic
|
||||
```
|
||||
|
||||
The following options are supported:
|
||||
|
||||
`mode`{: #mode }
|
||||
|
||||
: :octicons-milestone-24: Default: `view` – This option defines how the markup
|
||||
should be parsed, i.e. whether to just `view` all suggest changes, or
|
||||
alternatively `accept` or `reject` them:
|
||||
|
||||
=== "View changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: view
|
||||
```
|
||||
|
||||
=== "Accept changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: accept
|
||||
```
|
||||
|
||||
=== "Reject changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: reject
|
||||
```
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/critic/
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
### BetterEm
|
||||
|
||||
The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
|
||||
improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
|
||||
and can be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
```
|
||||
|
||||
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
|
||||
|
||||
### Caret, Mark & Tilde
|
||||
|
||||
The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
|
||||
Markdown Extensions][4], allow for the __highlighting of text__, as well as
|
||||
__handling sub- and superscripts__:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.caret
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
```
|
||||
|
||||
[6]: https://facelessuser.github.io/pymdown-extensions/caret/
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/mark/
|
||||
[8]: https://facelessuser.github.io/pymdown-extensions/tilde/
|
||||
|
||||
### SmartSymbols
|
||||
|
||||
The [SmartSymbols][9] extension, which is also part of [Python Markdown
|
||||
Extensions][4], __converts special characters into their corresponding
|
||||
symbols__, and can be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.smartsymbols
|
||||
```
|
||||
|
||||
See the [official documentation][9] for a list of supported symbols.
|
||||
|
||||
[9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
||||
|
||||
## Usage
|
||||
|
||||
### Highlighting changes
|
||||
|
||||
When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
|
||||
ability to _highlight suggested changes_, as well as add _inline comments_ to a
|
||||
document:
|
||||
|
||||
[10]: #critic
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
Text can be {--deleted--} and replacement text {++added++}. This can also be
|
||||
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
|
||||
possible {>>and comments can be added inline<<}.
|
||||
|
||||
{==
|
||||
|
||||
Formatting can also be applied to blocks, by putting the opening and closing
|
||||
tags on separate lines and adding new lines between the tags and the content.
|
||||
|
||||
==}
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
Text can be {--deleted--} and replacement text {++added++}. This can also be
|
||||
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
|
||||
possible {>>and comments can be added inline<<}.
|
||||
|
||||
{==
|
||||
|
||||
Formatting can also be applied to blocks, by putting the opening and closing
|
||||
tags on separate lines and adding new lines between the tags and the content.
|
||||
|
||||
==}
|
||||
|
||||
### Highlighting text
|
||||
|
||||
When the [Caret, Mark & Tilde][11] extensions are enabled, text can be
|
||||
highlighted with a nicer syntax than using the corresponding `mark`, `del` and
|
||||
`ins` HTML tags:
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* ^^This was inserted^^
|
||||
* ==This was marked==
|
||||
* ~~This was deleted~~
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* ^^This was inserted^^
|
||||
* ==This was marked==
|
||||
* ~~This was deleted~~
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
|
||||
### Sub- and superscripts
|
||||
|
||||
When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
|
||||
superscripted with a nicer syntax than using the corresponding `sub` and `sup`
|
||||
HTML tags:
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* A^T^A
|
||||
* H~2~0
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* A^T^A
|
||||
* H~2~0
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
@ -49,7 +49,7 @@ about configuration options.
|
||||
### Attribute List
|
||||
|
||||
The [Attribute List][10] extension, which is part of the standard Markdown
|
||||
library, allows to __add HTML attributes and classes to Markdown elements__,
|
||||
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
|
||||
and can be enabled via `mkdocs.yml`
|
||||
|
||||
``` yaml
|
||||
@ -141,16 +141,16 @@ Then, add the CSS classes to the icons:
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
- :fontawesome-brands-medium:{: .medium } – Medium
|
||||
- :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
* :fontawesome-brands-medium:{: .medium } – Medium
|
||||
* :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
* :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
- :fontawesome-brands-medium:{: .medium } – Medium
|
||||
- :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
* :fontawesome-brands-medium:{: .medium } – Medium
|
||||
* :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
* :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
|
||||
[17]: #attribute-list
|
||||
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
|
||||
|
||||
@ -59,16 +59,16 @@ theme:
|
||||
|
||||
Some popular choices:
|
||||
|
||||
- :fontawesome-brands-git: – `fontawesome/brands/git`
|
||||
- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
|
||||
- :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
|
||||
- :fontawesome-brands-github: – `fontawesome/brands/github`
|
||||
- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
|
||||
- :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
|
||||
- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
|
||||
- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
|
||||
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
|
||||
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
|
||||
* :fontawesome-brands-git: – `fontawesome/brands/git`
|
||||
* :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
|
||||
* :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
|
||||
* :fontawesome-brands-github: – `fontawesome/brands/github`
|
||||
* :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
|
||||
* :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
|
||||
* :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
|
||||
* :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
|
||||
* :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
|
||||
* :fontawesome-solid-trash: – `fontawesome/solid/trash`
|
||||
|
||||
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
|
||||
@ -37,16 +37,16 @@ For each entry, the following fields are available:
|
||||
This field must point to a valid icon path referencing [any icon bundled
|
||||
with the theme][2], or the build will not succeed. Some popular choices:
|
||||
|
||||
- :fontawesome-brands-behance: – `fontawesome/brands/behance`
|
||||
- :fontawesome-brands-docker: – `fontawesome/brands/docker`
|
||||
- :fontawesome-brands-github: – `fontawesome/brands/github`
|
||||
- :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
|
||||
- :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
|
||||
- :fontawesome-brands-medium: – `fontawesome/brands/medium`
|
||||
- :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
|
||||
- :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
|
||||
- :fontawesome-brands-slack: – `fontawesome/brands/slack`
|
||||
- :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
|
||||
* :fontawesome-brands-behance: – `fontawesome/brands/behance`
|
||||
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
|
||||
* :fontawesome-brands-github: – `fontawesome/brands/github`
|
||||
* :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
|
||||
* :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
|
||||
* :fontawesome-brands-medium: – `fontawesome/brands/medium`
|
||||
* :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
|
||||
* :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
|
||||
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
|
||||
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
@ -196,9 +196,9 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
: This mode is active when the _search is focused_. It provides several key
|
||||
bindings to make search accessible and navigable via keyboard:
|
||||
|
||||
- ++arrow-down++ , ++arrow-up++ : select next / previous result
|
||||
- ++esc++ , ++tab++ : close search dialog
|
||||
- ++enter++ : follow selected result
|
||||
* ++arrow-down++ , ++arrow-up++ : select next / previous result
|
||||
* ++esc++ , ++tab++ : close search dialog
|
||||
* ++enter++ : follow selected result
|
||||
|
||||
`global`{: #global }
|
||||
|
||||
@ -206,9 +206,9 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
focussed element that is susceptible to keyboard input. The following keys
|
||||
are bound:
|
||||
|
||||
- ++f++ , ++s++ , ++slash++ : open search dialog
|
||||
- ++p++ , ++comma++ : go to previous page
|
||||
- ++n++ , ++period++ : go to next page
|
||||
* ++f++ , ++s++ , ++slash++ : open search dialog
|
||||
* ++p++ , ++comma++ : go to previous page
|
||||
* ++n++ , ++period++ : go to next page
|
||||
|
||||
Let's say you want to bind some action to the ++x++ key. By using [additional
|
||||
JavaScript][11], you can subscribe to the `keyboard$` observable and attach
|
||||
|
||||
@ -256,15 +256,15 @@ message format using _discriminated unions_, i.e. through the `type` property
|
||||
of the message. See the following interface definitions to learn about the
|
||||
message formats:
|
||||
|
||||
- [:octicons-file-code-24: `SearchMessage`][17]
|
||||
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
|
||||
* [:octicons-file-code-24: `SearchMessage`][17]
|
||||
* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
|
||||
|
||||
The sequence and direction of messages is rather intuitive:
|
||||
|
||||
- :octicons-arrow-right-24: `SearchSetupMessage`
|
||||
- :octicons-arrow-left-24: `SearchReadyMessage`
|
||||
- :octicons-arrow-right-24: `SearchQueryMessage`
|
||||
- :octicons-arrow-left-24: `SearchResultMessage`
|
||||
* :octicons-arrow-right-24: `SearchSetupMessage`
|
||||
* :octicons-arrow-left-24: `SearchReadyMessage`
|
||||
* :octicons-arrow-right-24: `SearchQueryMessage`
|
||||
* :octicons-arrow-left-24: `SearchResultMessage`
|
||||
|
||||
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
|
||||
[16]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
|
||||
|
||||
@ -168,6 +168,7 @@ nav:
|
||||
- Code blocks: reference/code-blocks.md
|
||||
- Content tabs: reference/content-tabs.md
|
||||
- Footnotes: reference/footnotes.md
|
||||
- Formatting: reference/formatting.md
|
||||
- Icons + Emojis: reference/icons-emojis.md
|
||||
- Lists: reference/lists.md
|
||||
- MathJax: reference/mathjax.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user