Refactored JavaScript architecture

docs/extensions/admonition.md

@@ -85,7 +85,8 @@ paragraphs and other blocks – except code blocks, because the parser from the
 standard Markdown library does not account for those.
 
 However, the [PyMdown Extensions][] package adds an extension called
-`superfences`, which makes it possible to nest code blocks within other blocks.
+[SuperFences][], which makes it possible to nest code blocks within other
+blocks.
 
 Example:
 
@@ -310,3 +311,4 @@ Qualifiers:
 
 [Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html
 [PyMdown Extensions]: https://facelessuser.github.io/pymdown-extensions
+[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

docs/extensions/codehilite.md

@@ -6,8 +6,8 @@ executed during compilation of the Markdown file.
 
 ## Installation
 
-CodeHilite parses code blocks and wraps them in `pre` tags. If [Pygments][] is
-installed, which is a generic syntax highlighter with support for over
+CodeHilite parses code blocks and wraps them in `<pre>` tags. If [Pygments][]
+is installed, which is a generic syntax highlighter with support for over
 [300 languages][], CodeHilite will also highlight the code block. Pygments can
 be installed with the following command:
 

docs/extensions/metadata.md

@@ -1,3 +1 @@
 # Metadata
-
-Foobar

docs/extensions/permalinks.md

@@ -14,7 +14,7 @@ markdown_extensions:
   - toc(permalink=true)
 ```
 
-This will add a link containing the paragraph symbol "¶" at the end of each
+This will add a link containing the paragraph symbol `¶` at the end of each
 headline (exactly like on the page you're currently viewing), which the
 Material theme will make appear on hover. In order to change the text of the
 permalink, a string can be passed, e.g.:

docs/extensions/pymdown/arithmatex.md

@@ -0,0 +1,63 @@
+# Arithmatex <small>MathJax</small>
+
+[Arithmatex][] integrates [MathJax][] with Markdown and is included in the
+[PyMdown Extensions][] package. It parses block-style and inline equations
+written in TeX markup and outputs them in mathematical notation.
+
+## Installation
+
+Make sure that the PyMdown Extensions package [is installed][] 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.
+
+## Usage
+
+MathJax searches for `:::tex $$...$$` (blocks) and `:::tex $...$` (inline)
+equations, parses their contents and renders them in mathematical notation.
+See [this thread][] on StackExchange for a short introduction and quick
+reference on how to write equations in TeX syntax.
+
+### 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)}$
+
+[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+[MathJax]: https://www.mathjax.org/
+[PyMdown Extensions]: https://facelessuser.github.io/pymdown-extensions
+[is installed]: /extensions/pymdown/overview/#installation
+[this thread]: http://meta.math.stackexchange.com/questions/5020/

docs/extensions/pymdown/overview.md

@@ -1,37 +1,93 @@
 # PyMdown Extensions
 
 [PyMdown Extensions][] is a collection of Markdown extensions that add some
-great and missing 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.
+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 can be installed with the following command:
+The PyMdown Extensions package can be installed with the following command:
 
 ``` sh
 pip install pymdown-extensions
 ```
 
-## Usage
+## Extensions
 
-### Improvements on existing Markdown
+### GitHub Flavored Markdown
 
-- BetterEm
-- SuperFences
-- MagicLink
+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
 
-### New Syntax for...
+- Inlinehilite --- own documentation file
+- Critic --- own documentation file
 
-- Caret
-- Mark
-- Tilde
-
-### New features
-
-- Arithmatex
-- Inlinehilite
-- Tasklist
 
 [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/