From 04bacbd101b8eb57fcdeca0055b41de1b8fae20a Mon Sep 17 00:00:00 2001 From: squidfunk Date: Mon, 27 Jul 2020 12:05:07 +0200 Subject: [PATCH] Added docs on extended formatting --- docs/reference/admonitions.md | 2 +- docs/reference/code-blocks.md | 24 ++-- docs/reference/content-tabs.md | 36 ++--- docs/reference/formatting.md | 189 ++++++++++++++++++++++++++ docs/reference/icons-emojis.md | 14 +- docs/setup/adding-a-git-repository.md | 20 +-- docs/setup/adding-social-links.md | 20 +-- docs/setup/setting-up-navigation.md | 12 +- docs/setup/setting-up-site-search.md | 12 +- mkdocs.yml | 1 + 10 files changed, 260 insertions(+), 70 deletions(-) create mode 100644 docs/reference/formatting.md diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 9a8dfe49d..d582d570e 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -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 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index e99b86b78..934bd55c6 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -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 diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md index a1df1daaf..4d459cf38 100644 --- a/docs/reference/content-tabs.md +++ b/docs/reference/content-tabs.md @@ -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" diff --git a/docs/reference/formatting.md b/docs/reference/formatting.md new file mode 100644 index 000000000..38e3365ee --- /dev/null +++ b/docs/reference/formatting.md @@ -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 diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index da848d398..568898725 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -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 diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index a6e922231..587bec46b 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -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 diff --git a/docs/setup/adding-social-links.md b/docs/setup/adding-social-links.md index bd4078a59..4e3e048ee 100644 --- a/docs/setup/adding-social-links.md +++ b/docs/setup/adding-social-links.md @@ -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 diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 18c629ee1..7077ae380 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -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 diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 7d046a55f..486885585 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index ee2bde6fe..0ce79b926 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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