1
0
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 2020-07-27 12:05:07 +02:00
parent 807fbdb1bc
commit 04bacbd101
10 changed files with 260 additions and 70 deletions

View File

@ -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

View File

@ -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

View File

@ -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"

View 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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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