Full integration with PyMdown extensions

.sass-lint.yml

@@ -22,6 +22,7 @@ files:
   ignore:
     - node_modules/**
     - src/assets/stylesheets/extensions/pymdown/_arithmatex.scss
+    - src/assets/stylesheets/extensions/pymdown/_critic.scss
     - src/assets/stylesheets/extensions/pymdown/_inlinehilite.scss
     - src/assets/stylesheets/_shame.scss
 

docs/extensions/pymdown.md

@@ -0,0 +1,229 @@
+# PyMdown Extensions
+
+[PyMdown Extensions][1] is a collection of Markdown extensions that add some
+great features to the standard Markdown library. For this reason, the
+**installation of this package is highly recommended** as it's well-integrated
+with the Material theme.
+
+  [1]: http://facelessuser.github.io/pymdown-extensions/
+
+## Installation
+
+The PyMdown Extensions package can be installed with the following command:
+
+``` sh
+pip install pymdown-extensions
+```
+
+The following list of extensions that are part of the PyMdown Extensions package
+are recommended to be used together with the Material theme:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.betterem
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.githubemoji
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist(custom_checkbox=true)
+  - pymdownx.tilde
+```
+
+Additionally, there is a [MathJax integration](#arithmatex) which should only
+be switched on if needed, as it adds a few hundred kb of JavaScript:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.arithmatex
+```
+
+## Extensions
+
+### GitHub Flavored Markdown
+
+Most of the extensions included in the PyMdown Extensions package try to bring
+the Markdown experience closer to GitHub Flavored Markdown (GFM).
+
+The PyMdown Extensions package adds a shorthand to enable all of the included
+extensions that provide the GFM experience. However, usage of the shorthand is
+discouraged, because some extensions are not supported, as the Material theme
+uses the counterparts included in the standard Markdown library.
+
+#### BetterEm
+
+[BetterEm][2] improves the handling of emphasis markup (**bold** and *italic*)
+within Markdown by providing a more sophisticated parser for better detecting
+start and end tokens. Read the documentation for [usage notes][3].
+
+  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+  [3]: https://facelessuser.github.io/pymdown-extensions/usage_notes/
+
+#### GitHub Emoji
+
+[GitHub Emoji][4] adds the ability to insert emojis, which does not only
+include the :octocat: emojis, but also a :shit:-load of emojis that we use in
+our daily lives. See the [Emoji Cheat Sheet][5] for a list of all available
+emojis. Happy scrolling :tada:
+
+  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/githubemoji/
+  [5]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
+
+#### MagicLink
+
+[MagicLink][6] detects links in Markdown and auto-generates the necessary
+markup, so no special syntax is required. It auto-links HTTP(S) and FTP links,
+as well as references to email addresses:
+
+  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
+
+#### SuperFences
+
+[SuperFences][7] provides the ability to nest code blocks under blockquotes,
+lists and other block elements, which the [Fenced Code Blocks][8] extension
+from the standard Markdown library doesn't parse correctly.
+
+  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+  [8]: https://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html
+
+#### Tasklist
+
+[Tasklist][9] adds support for styled checkbox lists. This is useful for
+keeping track of tasks and showing what has been done and has yet to be done.
+Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or
+`[x]` for filled checkboxes.
+
+Example:
+
+``` markdown
+* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+* [x] Nulla lobortis egestas semper
+* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
+* [ ] Vestibulum convallis sit amet nisi a tincidunt
+    * [x] In hac habitasse platea dictumst
+    * [x] In scelerisque nibh non dolor mollis congue sed et metus
+    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
+    * [ ] Praesent sed risus massa
+* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
+```
+
+Result:
+
+* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+* [x] Nulla lobortis egestas semper
+* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
+* [ ] Vestibulum convallis sit amet nisi a tincidunt
+    * [x] In hac habitasse platea dictumst
+    * [x] In scelerisque nibh non dolor mollis congue sed et metus
+    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
+    * [ ] Praesent sed risus massa
+* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
+
+[9]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
+
+#### Tilde
+
+[Tilde][10] provides an easy way to ~~strike through~~ cross out text.
+The portion of text that should be erased must be enclosed in two tildes
+`~~...~~`, and the extension will take care of the rest.
+
+  [10]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
+
+### More syntactic sugar
+
+#### Caret
+
+[Caret][11] is the sister extension of [Tilde](#tilde) and makes it possible to
+highlight ^^inserted text^^. The portion of text that should be marked as added
+must be enclosed in two carets `^^...^^`.
+
+  [11]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
+
+#### Mark
+
+[Mark][12] adds the ability to ==highlight text== like it was marked with a
+==yellow text marker==. The portion of text that should be highlighted must be
+enclosed in two equal signs `==...==`.
+
+  [12]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
+
+#### SmartSymbols
+
+[SmartSymbols][13] converts markup for special characters into their
+corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
+symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
+
+  [13]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+
+#### Critic
+
+[Critic][14] implements [Critic Markup][15], a Markdown extension that enables
+the tracking of changes (additions, deletions and comments) on documents.
+During compilation of the Markdown document, changes can be rendered (default),
+accepted or rejected.
+
+Text can be {--deleted--} and replacement text {++added++}. This can also be
+combined in {~~one~>a single~~} operation. {==Highlighting==} is also possible
+{>>and comments can be added inline<<}.
+
+  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
+  [15]: http://criticmarkup.com/
+
+### Math and code highlighting
+
+#### Arithmatex
+
+[Arithmatex][16] integrates Material with [MathJax][17] which parses
+block-style and inline equations written in TeX markup and outputs them in
+mathematical notation. See [this thread][18] for a short introduction and quick
+reference on how to write equations in TeX syntax.
+
+  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+  [17]: https://www.mathjax.org/
+  [18]: http://meta.math.stackexchange.com/questions/5020/
+
+##### Blocks
+
+Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines.
+
+Example:
+
+``` tex
+$$
+\frac{n!}{k!(n-k)!} = \binom{n}{k}
+$$
+```
+
+Result:
+
+$$
+\frac{n!}{k!(n-k)!} = \binom{n}{k}
+$$
+
+##### Inline
+
+Inline equations need to be enclosed in `:::tex $...$`:
+
+Example:
+
+``` tex
+Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
+```
+
+Result:
+
+Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
+
+#### Inlinehilite
+
+[Inlinehilite][19] adds support for inline code highlighting. It's useful for
+short snippets included within body copy, e.g. `#!js var test = 0;` and can be
+achived by prefixing inline code with a shebang and language identifier,
+e.g. `#!js`.
+
+  [19]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/

docs/extensions/pymdown/arithmatex.md

@@ -1,65 +0,0 @@
-# Arithmatex <small>MathJax</small>
-
-[Arithmatex][1] integrates [MathJax][2] with Markdown and is included in the
-[PyMdown Extensions][3] package. It parses block-style and inline equations
-written in TeX markup and outputs them in mathematical notation.
-
-  [1]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
-  [2]: https://www.mathjax.org/
-  [3]: https://facelessuser.github.io/pymdown-extensions
-
-## Installation
-
-Make sure that the PyMdown Extensions package [is installed][4] and add the
-following lines to your `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.arithmatex
-```
-
-The MathJax runtime is automatically included if the extension is enabled, so
-there is no need for extra JavaScript.
-
-  [4]: /extensions/pymdown/overview/#installation
-
-## Usage
-
-MathJax searches for `:::tex $$...$$` (blocks) and `:::tex $...$` (inline)
-equations, parses their contents and renders them in mathematical notation.
-See [this thread][5] on StackExchange for a short introduction and quick
-reference on how to write equations in TeX syntax.
-
-  [5]: http://meta.math.stackexchange.com/questions/5020/
-
-### Blocks
-
-Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines.
-
-Example:
-
-``` tex
-$$
-\frac{n!}{k!(n-k)!} = \binom{n}{k}
-$$
-```
-
-Result:
-
-$$
-\frac{n!}{k!(n-k)!} = \binom{n}{k}
-$$
-
-### Inline
-
-Inline equations need to be enclosed in `:::tex $...$`:
-
-Example:
-
-``` tex
-Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
-```
-
-Result:
-
-Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$

docs/extensions/pymdown/inlinehilite.md

@@ -1,24 +0,0 @@
-# Inlinehilite
-
-The [Inlinehilite][1] extension included in the [PyMdown Extensions][2] package
-adds support for inline code highlighting. It's useful for short snippets
-included with body copy.
-
-  [1]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
-  [2]: https://facelessuser.github.io/pymdown-extensions
-
-## Installation
-
-Make sure that the PyMdown Extensions package [is installed][] and add the
-following lines to your `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.inlinehilite
-```
-
-## Usage
-
-Syntax is similar to usual code highlighting, with the langauge shebang followed by one space. If you need to escape the highlight (like we're about to), add a space prior to the shebang.
-
-For example, `#!js var test = 0;`, which was achieved using ` #!js var test = 0;`. Alternatively, you can use the triple colon, ` :::js var test = 0;` to produce the same result, `:::js var test = 0;`.

docs/extensions/pymdown/overview.md

@@ -1,92 +0,0 @@
-# PyMdown Extensions
-
-[PyMdown Extensions][] is a collection of Markdown extensions that add some
-great features to the standard Markdown library. For this reason, the
-**installation of this package is highly recommended** as it's well-integrated
-with the Material theme.
-
-## Installation
-
-The PyMdown Extensions package can be installed with the following command:
-
-``` sh
-pip install pymdown-extensions
-```
-
-## Extensions
-
-### GitHub Flavored Markdown
-
-Most of the extensions included in the PyMdown Extensions package try to bring
-the Markdown experience closer to GitHub Flavored Markdown (GFM):
-
-- [BetterEm][] improves the handling of emphasis markup (**bold** and *italic*)
-  within Markdown by providing a more sophisticated parser for better detecting
-  start and end tokens. Read the documentation for usage notes.
-
-- [MagicLink][] detects links in Markdown and auto-generates the necessary
-  markup, so no special syntax is required. It auto-links HTTP(S) and FTP
-  links, as well as references to email addresses.
-
-- [GitHub Emoji][] adds the ability to insert emojis, which does not only
-  include the :octocat: emojis, but also a :shit:-load of emojis that we use in
-  our daily lives. See the [Emoji Cheat Sheet][] for a list of all available
-  emojis. Happy scrolling :tada:
-
-- [SuperFences][] provides the ability to nest code blocks under blockquotes,
-  lists and other block elements, which the [Fenced Code Blocks][] extension
-  from the standard Markdown library doesn't parse correctly.
-
-- [Tasklist][] adds support for styled checkbox lists. This is useful for
-  keeping track of tasks and showing what has been done and has yet to be done.
-  The usage of this extension is documented [here][].
-
-- [Tilde][] provides an easy way to ~~strike through~~ cross out text.
-  The portion of text that should be erased must be enclosed in two tildes
-  `~~...~~`, and the extension will take care of the rest.
-
-The PyMdown Extensions package adds a shorthand to enable all of the included
-extensions that provide the GFM experience. However, usage of the shorthand is
-discouraged, because some extensions are not supported, as the Material theme
-uses the counterparts included in the standard Markdown library.
-
-To enable all extensions add the following lines to your `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.betterem
-  - pymdownx.githubemoji
-  - pymdownx.magiclink
-  - pymdownx.superfences
-  - pymdownx.tasklist(custom_checkbox=true)
-  - pymdownx.tilde
-```
-
-### Syntactic Sugar
-
-There are three other extensions that add further syntactic sugar:
-
-- [Caret][] is the sister extension of [Tilde][] and makes it possible to
-  highlight ^^inserted text^^. The portion of text that should be marked as
-  added must be enclosed in two carets `^^...^^`, the extension will do the
-  rest.
-
-- [Mark][] add the ability to ==mark text==.
-- SmartSymbols
-
-- Inlinehilite --- own documentation file
-- Critic --- own documentation file
-
-[PyMdown Extensions]: http://facelessuser.github.io/pymdown-extensions/
-[usage notes]: https://facelessuser.github.io/pymdown-extensions/usage_notes/
-[BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
-[MagicLink]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
-[GitHub Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/githubemoji/
-[Emoji Cheat Sheet]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
-[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-[Fenced Code Blocks]: https://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html
-[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
-[here]: /extensions/pymdown/tasklist
-[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
-[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
-[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/

docs/extensions/pymdown/tasklist.md

@@ -1,56 +0,0 @@
-# Tasklist
-
-The [Tasklist][1] extension included in the [PyMdown Extensions][2] package
-adds support for styled checkbox lists. This is useful for keeping track of
-tasks and showing what has been done and has yet to be done.
-
-  [1]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
-  [2]: https://facelessuser.github.io/pymdown-extensions
-
-## Installation
-
-Make sure that the PyMdown Extensions package [is installed][3] and add the
-following lines to your `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.tasklist(custom_checkbox=true)
-```
-
-The `custom_checkbox` flag adds additional markup for better styling, so it is
-highly recommended to add this flag, as the Material theme supports it.
-
-  [3]: /extensions/pymdown/overview/#installation
-
-## Usage
-
-Checkbox lists are like regular lists, but prefixed with `[ ]` empty or `[x]`
-filled checkboxes.
-
-Example:
-
-``` markdown
-* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
-* [x] Nulla lobortis egestas semper
-* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
-* [ ] Vestibulum convallis sit amet nisi a tincidunt
-    * [x] In hac habitasse platea dictumst
-    * [x] In scelerisque nibh non dolor mollis congue sed et metus
-    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
-    * [ ] Praesent sed risus massa
-* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
-* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
-```
-
-Result:
-
-* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
-* [x] Nulla lobortis egestas semper
-* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
-* [ ] Vestibulum convallis sit amet nisi a tincidunt
-    * [x] In hac habitasse platea dictumst
-    * [x] In scelerisque nibh non dolor mollis congue sed et metus
-    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
-    * [ ] Praesent sed risus massa
-* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
-* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

material/base.html

@@ -36,7 +36,7 @@
       {% include "partials/webfonts.html" %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-dd5a9fb539.css">
+      <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-990f733f65.css">
       {% if config.extra.palette %}
         <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-535e87ca3f.palette.css">
       {% endif %}

mkdocs.yml

@@ -41,8 +41,8 @@ extra:
     primary: indigo
     accent: indigo
   font:
-    text: Ubuntu
-    mono: Ubuntu Mono
+    text: Roboto
+    mono: Roboto Mono
   social:
     - type: github
       link: https://github.com/squidfunk
@@ -82,11 +82,7 @@ pages:
     - Footnotes: extensions/footnotes.md
     - Metadata: extensions/metadata.md
     - Permalinks: extensions/permalinks.md
-    - PyMdown:
-      - Overview: extensions/pymdown/overview.md
-      - Inline Hilite: extensions/pymdown/inlinehilite.md
-      - Arithmatex: extensions/pymdown/arithmatex.md
-      - Tasklist: extensions/pymdown/tasklist.md
+    - PyMdown: extensions/pymdown.md
   - Specimen: specimen.md
   - Customization: customization.md
   - License: license.md

src/assets/stylesheets/base/_typeset.scss

@@ -273,12 +273,6 @@ kbd {
     word-break: break-word;
   }
 
-  // Text insertion and deletion markers
-  del,
-  ins {
-    color: $clr-red-500;
-  }
-
   // Text highlighting marker
   mark {
     margin: 0 0.25em;

src/assets/stylesheets/extensions/pymdown/_critic.scss

@@ -24,20 +24,42 @@
 // Rules
 // ----------------------------------------------------------------------------
 
-// Critic extension
-.critic {
+// Scoped in typesetted content to match specificity of regular content
+.md-typeset {
 
-  // Comment
-  &.comment {
+  // Deletions, additions and comments
+  del.critic,
+  ins.critic,
+  .comment.critic {
     margin: 0 0.25em;
     padding: 0.0625em 0;
     border-radius: 0.2rem;
-    background-color: $md-code-background;                                            // TODO: rename, centralize somehow
+    box-decoration-break: clone;
+  }
+
+  // Deletion
+  del.critic {
+    background-color: $codehilite-diff-deleted;                                 // TODO: dependent on order of inclusion
+    box-shadow:
+       0.25em 0 0 $codehilite-diff-deleted,
+      -0.25em 0 0 $codehilite-diff-deleted;
+  }
+
+  // Addition
+  ins.critic {
+    background-color: $codehilite-diff-inserted;
+    box-shadow:
+       0.25em 0 0 $codehilite-diff-inserted,
+      -0.25em 0 0 $codehilite-diff-inserted;
+  }
+
+  // Comment
+  .comment.critic {
+    background-color: $md-code-background;                                      // TODO: rename, centralize somehow
     color: $md-code-color;
     box-shadow:
        0.25em 0 0 $md-code-background,
       -0.25em 0 0 $md-code-background;
-    box-decoration-break: clone;
 
     // Icon
     &::before {

src/assets/stylesheets/extensions/pymdown/_emoji.scss

@@ -24,7 +24,11 @@
 // Rules
 // ----------------------------------------------------------------------------
 
-// Correct alignment of emojis
-.emoji {
-  vertical-align: text-top;
+// Scoped in typesetted content to match specificity of regular content
+.md-typeset {
+
+  // Correct alignment of emojis
+  .emoji {
+    vertical-align: text-top;
+  }
 }