Doc improvements

doc_theme/base.html

@@ -22,12 +22,12 @@
   <link href="{{ path }}" rel="stylesheet">
   {%- endfor %}
 
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.2/raphael-min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.7.0/underscore-min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.4/sequence-diagram-min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.4/raphael-min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.4.2/flowchart.min.js"></script>
   <script src="{{ base_url }}/js/jquery-2.1.1.min.js"></script>
   <script src="{{ base_url }}/js/modernizr-2.8.3.min.js"></script>
-  <script src="{{ base_url }}/js/flowchart-min.js"></script>
   <script src="{{ base_url }}/js/theme.js"></script>
   <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
   {%- block extrahead %} {% endblock %}

docs/extensions/arithmatex.md

@@ -10,9 +10,46 @@ The Arithmatex extension searches for `#!tex $...$` or `#!tex $$...$$` and forma
 
 `#!tex $$...$$` is the *display* or *block* form.  When using `#!tex $$`, the block must start with `#!tex $$` and end with `#!tex $$`; a block contains no empty lines.
 
-The Arithmatex extension actually converts the dollar notation to a more reliable notation in the HTML.  So the conversion is as follows: `#!tex $...$` -> `#!tex \(...\)` and `#!tex $$...$$` -> `#!tex \[...\]`.  Keep this in mind when configuring MathJax for your document.
-
-Arithmatex requires you to point the HTML at the MathJax library and provide the necessary configuration.  If using the PyMdown application, and not *just* the extension, PyMdown provides a script `mathjax-loader.js` for quick setup, though you still need to actually configure your settings to use the script and also point it at the library or cdn: `https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML`.  The PyMdown loader script does not have to be used, but is provided for quick startup and as an example.  Please see the [MathJax](http://www.mathjax.org/) site form more info on using MathJax.
+The Arithmatex extension actually converts the dollar notation to a more reliable notation in the HTML.  So the conversion is as follows: `#!tex $...$` --> `#!tex \(...\)` and `#!tex $$...$$` --> `#!tex \[...\]`.  Keep this in mind when configuring MathJax for your document.
+
+Arithmatex requires you to point the HTML at the MathJax library and provide the necessary configuration.  The recommended way of including MathJax is to use the CDN:
+
+```html
+<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+```
+
+Here is an example of setting up MathJax configuration:
+
+```js
+/* mathjax-loader.js */
+(function (win, doc) {
+  win.MathJax = {
+    config: ["MMLorHTML.js"],
+    extensions: ["tex2jax.js"],
+    jax: ["input/TeX"],
+    tex2jax: {
+      inlineMath: [ ["\\(","\\)"] ],
+      displayMath: [ ["\\[","\\]"] ]
+    },
+    TeX: {
+      TagSide: "right",
+      TagIndent: ".8em",
+      MultLineWidth: "85%",
+      equationNumbers: {
+        autoNumber: "AMS",
+      },
+      unicode: {
+        fonts: "STIXGeneral,'Arial Unicode MS'"
+      }
+    },
+    displayAlign: 'left',
+    showProcessingMessages: false,
+    messageStyle: 'none'
+  };
+})(window, document);
+```
+
+Please see the [MathJax](http://www.mathjax.org/) site for more info on using MathJax.
 
 ## Examples
 

docs/extensions/betterem.md

@@ -4,7 +4,7 @@ Better Emphasis.
 ---
 
 ## Overview
-BetterEm is an extension that aims to improve emphasis (bold and italic) handling.  It provides two modes for both asterisk and underscore bold and italics: **smart** when `smart_enable` is turned on and normal if `smart_enable` is turned off.  BetterEm overrides all the current bold and italic rules in Python Markdown with its own.  When **smart** is enabled for either asterisks and/or underscores, it is enabled for all variants: single, double, and triple.  When **smart** is enabled, the behavior will be very similar in feel to GFM bold and italic (but not necessarily exact).
+BetterEm is an extension that aims to improve emphasis (bold and italic) handling.  It provides two modes for both asterisk's and underscore's bold and italic: **smart** when `smart_enable` is turned on and normal if `smart_enable` is turned off.  BetterEm overrides all the current bold and italic rules in Python Markdown with its own.  When **smart** is enabled for either asterisks and/or underscores, it is enabled for all variants: single, double, and triple.  When **smart** is enabled, the behavior will be very similar in feel to GFM bold and italic (but not necessarily exact).
 
 !!! Caution "Reminder"
     Remember to read the [Usage Notes](../usage_notes.md) for information that may be relevant when using this extension!

docs/extensions/critic.md

@@ -4,7 +4,7 @@ Process and visualize Critic Markup.
 ---
 
 ## Overview
-Critic is an extension that adds handling and support of [Critic Markup](http://criticmarkup.com/).  This extension runs before all other extensions to parse the critic edits.  It allows for the stripping or accepting of critic modifications and modifies the source to reflect the rejection or accepting of the edits (mark wrappers and comments are stripped in both cases).  It also allows for visually displaying the changes in HTML output ([mileage may vary](#limitations-with-previewing-critic-markup)).
+Critic is an extension that adds handling and support of [Critic Markup](http://criticmarkup.com/).  This extension runs before all other extensions to parse the critic edits.  It allows for the removal or acceptance of the critic modifications and modifies the source to reflect the rejection or approval (highlights and comments are stripped in both cases).  It also allows for visually displaying the changes in HTML output ([mileage may vary](#limitations-with-previewing-critic-markup)).
 
 ## Options
 
@@ -13,9 +13,9 @@ Critic is an extension that adds handling and support of [Critic Markup](http://
 | mode | string | view | `view` just parses the markup and displays it in its HTML equivalent rendering.  `accept` strips out the critic markup and replacing them with the suggested changes.  `reject` rejects all the suggestions and strips the critic markup out replacing it with the original. |
 
 ## Limitations with Previewing Critic Markup
-CriticMarkup, in general works very well.  Parsing the critic marks is very straight forward.  If you need to reject critic marks or accept them, the critic extension will work quite well.  But when trying to render the edits visually **and** trying to convert the document to HTML, things can get ugly.  I think this is really a design flaw with CriticMarkup.  The existence of the critic edits can alter the actual source.  Its a fantastic idea, but it should be understood that when using CriticMarkup beyond inline or block paragraphs, there is a possibility that invalid HTML will be created when viewing (especially in relation to lists or if breaking up Markdown syntax).  I think Fletcher said it best here: http://fletcher.github.io/MultiMarkdown-4/criticmarkup.
+Parsing CriticMarkup is very straight forward.  If you need to reject critic marks or accept them, the critic extension will work quite well.  But when trying to render the edits visually **and** trying to convert the document to HTML, things can get ugly.  I think this is the one unfortunate problem with CriticMarkup.  The existence of the critic edits can alter the actual source.  Its a fantastic idea, but it should be understood that when using CriticMarkup beyond inline or block paragraphs, there is a possibility that invalid HTML will be created when viewing (especially in relation to lists or if breaking up Markdown syntax).  I think Fletcher said it best here: http://fletcher.github.io/MultiMarkdown-4/criticmarkup.
 
-The critic extension does its best by employing a preprocessor to inject the critic tags before all other parsing and a post-processor to clean up some the weird side effects of the injection (only selected odd cases as others are more difficult to fix).  It injects some classes into the edit region's HTML output to allow for CSS styling to render them as well.  There is probably a lot more post-processing that could be done to fix more issues, but I am not yet sure how much further down that road I am willing to go.
+The critic extension does its best by employing a preprocessor to inject the critic tags before all other parsing and a post-processor to clean up some the weird side effects of the injection (only selected odd cases as others are more difficult to fix).  It injects some classes into the edit region's HTML output which allows for CSS styling.  There is probably a lot more post-processing that could be done to fix more issues, but I am not yet sure how much further down that road I am willing to go.
 
 ## Examples
 | Markup    |  Example |

docs/extensions/extra.md

@@ -4,11 +4,11 @@ PHP Markdown Extra extensions.
 ---
 
 ## Overview
-Python Markdown provides an `extra` extension to provide features similar to PHP Markdown Extra.  PyMdown aims to provide not only new features, but to improve behavior in Python Markdown's existing feature set.  Some of things can be at odds.  Python Markdown's `smartstrong` and `fenced_code` are not compatible with PyMdown's `betterem` and `superfences`.  `smartstong` should never be loaded at the same time as `betterem`, and `superfences` should not be loaded at the same time as `fenced_code`.  Because of this, it is not possible to use Python Markdown's `extra` and PyMdown's `superfences` and `betterem`. To make this less frustrating, PyMdown provides it's own implementation of `extra`.
+Python Markdown provides an `extra` extension to provide features similar to PHP Markdown Extra.  PyMdown Extensions aims to provide not only new features, but to improve behavior in Python Markdown's existing feature set.  Some of these things can be at odds.  Python Markdown's `smartstrong` and `fenced_code` are not compatible with PyMdown Extensions' `betterem` and `superfences`.  `smartstong` should never be loaded at the same time as `betterem`, and `superfences` should not be loaded at the same time as `fenced_code`.  Because of this, it is not possible to use Python Markdown's `extra` and PyMdown's `superfences` and `betterem`. To make this less frustrating, PyMdown provides it's own implementation of `extra`.
 
 PyMdown's `extra` is just like Python Markdown's extra except `smartstrong` is replaced by `betterem` and `fenced_code` is replaced by `superfences`.  All other features and extensions should be identical because we are using the same ones.
 
-The PyMdown extension is a convenience extension and it currently provides no other additional features.  But remember **don't use `pymdownx.extra` while also using `markdown.extensions.extra`**!
+This extension is a convenience extension, and it currently provides no other additional features.  But remember **don't use `pymdownx.extra` while also using `markdown.extensions.extra`**!
 
 !!! Caution "Reminder"
     Remember to read the [Usage Notes](../usage_notes.md) for information that may be relevant when using this extension!

docs/extensions/extrarawhtml.md

@@ -4,4 +4,4 @@ PHP Markdown Extra's raw HTML parsing.
 ---
 
 ## Overview
-Python Markdown provides an `extra` extension to provide features similar to PHP Markdown Extra.  For reasons covered in [pymdownx.extra](./extra.md), PyMdown implements its own `extra` extension.  In order to accomplish this, Python Markdown's raw HTML parsing functionality, which is used to parse nested markdown inside HTML blocks, had to be split out of the `extra` implementation.  Afterwards, it was decided to leave it completely separate to allow people who maybe didn't want to use all of the features found in `extra`, but still wanted to use the parsing of nested Markdown inside of HTML blocks.  This is basically a wrapper around Python Markdown's `extra` extension, but it only implements the raw HTML parsing.  For more info see [Python Markdown's Extra documentation](https://pythonhosted.org/Markdown/extensions/extra.html#nested-markdown-inside-html-blocks).
+Python Markdown provides an `extra` extension to provide features similar to PHP Markdown Extra.  For reasons covered in [pymdownx.extra](./extra.md), PyMdown Extensions implements its own `extra` extension.  In order to accomplish this, Python Markdown's raw HTML parsing functionality, which is used to parse nested markdown inside HTML blocks, had to be split out of the `extra` implementation.  Afterwards, it was decided to leave it completely separate to allow people who maybe didn't want to use all of the features found in `extra`, but still wanted to use the parsing of nested Markdown inside of HTML blocks.  This is basically a wrapper around Python Markdown's `extra` extension, but it only implements the raw HTML parsing.  For more info see [Python Markdown's Extra documentation](https://pythonhosted.org/Markdown/extensions/extra.html#nested-markdown-inside-html-blocks).

docs/extensions/inlinehilite.md

@@ -22,7 +22,7 @@ By default, InlineHilite will use CodeHilite's settings if it is being used, but
 | use_codehilite_settings | bool | True | Determine whether CodeHilite's settings should be used, or if InlineHilite should use a different set. |
 | guess_lang | bool | True | If ignoring CodeHilite's settings, determine whether InlineHilite should try to guess a code block's language if not specified. |
 | css_class | string | 'inlinehilite' | If ignoring CodeHilite's settings, this is the class name that will be injected into code tags when they are processed. |
-| pygments_style | string | 'default' | If ignoring CodeHilite's settings, this is the pygments style to use.  When using Python Markdown, this really only has an effect when using `noclasses`.  But when paired with the PyMdown tool, PyMdown will actually include the relevant CSS. |
+| pygments_style | string | 'default' | If ignoring CodeHilite's settings, this is the pygments style to use.  When using Python Markdown, this really only has an effect when using `noclasses`. |
 | noclasses | bool | False | If ignoring CodeHilite's settings, this will cause the styles to directly be written to the tag's style attribute instead of requiring a stylesheet. |
 | use_pygments | bool | True | If Pygments is available, and if ignoring CodeHilite's settings, this will control whether Pygements is used on the code block, or if the block's content will just be escaped and prepped for a JavaScript syntax highlighter. |
 

docs/extensions/magiclink.md

@@ -11,14 +11,14 @@ GFM has a nice feature that detects and auto-generates links.  This extension ad
 ```
 This requires no special syntax.
 
-Just paste links directly in the document like this: https://github.com/facelessuser/PyMdown.
+Just paste links directly in the document like this: https://github.com/facelessuser/pymdown-extensions.
 
 Or even an email address [email protected].
 ```
 
 This requires no special syntax.
 
-Just paste links directly in the document like this: https://github.com/facelessuser/PyMdown.
+Just paste links directly in the document like this: https://github.com/facelessuser/pymdown-extensions.
 
 Or even an email address [email protected].
 

docs/extensions/plainhtml.md

@@ -10,7 +10,7 @@ PlainHtml is a simple extension that is run at the end of post-processing.  It s
     This is not meant to be a sanitizer for HTML.  This is just meant to try and strip out style, script, classes, etc. to provide a plain HTML output for the times this is desired; this is not meant as a security extension.  If you want something to secure the output, you should consider running a sanitizer like [bleach](https://pypi.python.org/pypi/bleach).
 
 ## Options
-By default, PlainHtml strips the following attributes: `style`, `id`, `class`, and `on<name>`.  PlainHtml also strips HTML comments. If desired, its behavior can be configured to strip less or even more, but it is limited to attributes and comments.  If you are using the [PyMdown app](https://github.com/facelessuser/PyMdown), and you want to control what gets stripped, you may want to forgo using the `--plain-html` option laid out in the [user guide](http://facelessuser.github.io/PyMdown/user-guide/general-usage/#plain-html) and just configure the plugin manually; the `--plain-html` option runs with the defaults only.
+By default, PlainHtml strips the following attributes: `style`, `id`, `class`, and `on<name>`.  PlainHtml also strips HTML comments. If desired, its behavior can be configured to strip less or even more, but it is limited to attributes and comments.
 
 | Option    | Type | Default |Description |
 |-----------|------|---------|------------|

docs/extensions/superfences.md

@@ -66,8 +66,16 @@ When using the UML diagram features, you must provide the necessary JavaScript f
 - [underscore.js](http://underscorejs.org/)
 - [sequece-diagram.js](http://bramp.github.io/js-sequence-diagrams/)
 
+All of these libraries can be included using a CDN (you can use the version of your choice):
 
-Simply including the libraries above is not enough as these libraries need to be pointed at the elements they need to convert.  If using the PyMdown application, and not just the extension, PyMdown provides scripts `uml-converter.js`, `flow-loader.js`, and `sequence-loader.js` that can be used to target the HTML elements and execute the appropriate library on their content to create the desired diagrams.  The scripts do not have to be used, and you can modify them or write your own to suite your needs; it is provided for convenience.
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.4/raphael-min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.4.2/flowchart.min.js"></script>
+```
+
+Simply including the libraries above is not enough as these libraries need to be pointed at the elements they need to convert.  Here we are going to show some examples (`uml-converter.js`, `flow-loader.js`, and `sequence-loader.js`) that can be used to target the HTML elements and execute the appropriate library on their content to create the desired diagrams.  The scripts do not have to be used, and you can modify them or write your own to suite your needs; it is provided for convenience.
 
 ```js
 /* uml-converter.js */

docs/index.md

@@ -1,12 +1,12 @@
 # Extensions {: .doctitle}
-PyMdown extensions.
+PyMdown Extensions.
 
 ---
 
 ## Available Extensions
 PyMdown Extensions provides a handful of extensions for use with Python Markdown.  Keep in mind, the PyMdown extensions were designed to work with the default extensions, so your mileage may vary in regards to compatibility when paired with other 3rd party extensions.
 
-Check out the individual extension document pages for more info on the available PyMdown extensions.
+Check out the individual extension document pages for more info on the available extensions.
 
 !!! Caution "Reminder"
     Please read the [Usage Notes](usage_notes.md) for information on extension compatibility and general notes to be aware of when using these extensions.