From 0676ae1f4b105aa90ba6fdb5fb22636f2399e2c6 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 28 Feb 2021 14:23:11 +0100 Subject: [PATCH] Documentation --- docs/insiders.md | 24 +++++---- docs/reference/code-blocks.md | 95 +++++++++++++++++++++++++++-------- 2 files changed, 88 insertions(+), 31 deletions(-) diff --git a/docs/insiders.md b/docs/insiders.md index 16037b6a4..217bd2c4e 100644 --- a/docs/insiders.md +++ b/docs/insiders.md @@ -112,6 +112,7 @@ The following features are currently exclusively available to sponsors:
+- [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 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index f81ff4d07..6d8f90f7a 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -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_: + +
+ +[![Annotations][19]][19] + +
+ +A demo is worth a thousand words — check it out at +[squidfunk.github.io/mkdocs-material-insiders][20] + +
+
+ +_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=""` @@ -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