mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2026-08-01 02:08:46 -04:00
Added docs on extended formatting
This commit is contained in:
squidfunk
@@ -246,7 +246,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
|
||||
purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
`info`{: #info}, `todo`
|
||||
`info`{: #info }, `todo`
|
||||
|
||||
: !!! info
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user