Update documentation for 8.0 (#1050)

docs/src/dictionary/en-custom.txt

@@ -138,6 +138,7 @@ emojione
 escaper
 facelessuser
 formatter
+formatter's
 formatters
 gantt
 gemoji

docs/src/markdown/about/changelog.md

@@ -4,20 +4,22 @@
 
 Please see [Release Notes](./release.md#upgrading-to-80) for details on upgrading to 8.0.
 
+- **NEW**: Added SaneHeaders extension.
 - **NEW**: SuperFences \& InlineHilite: gracefully handle failing custom formatters and/or validators. Users should add
   their own debug code to their formatter/validator if they suspect it isn't working.
 - **NEW**: SuperFences: if a custom fence validator fails, try the next custom fence until all are exhausted.
-- **NEW**: SuperFences: no longer allow custom options in the form `key=`. Only keys with values or keys with no value
-  and no `=` are accepted. Keys with no value will now assume the value to be the key name.
+- **NEW**: SuperFences: no longer allow custom options in the form `key=` (no value). Only keys with values or keys with
+  no value and no `=` are accepted. Keys with no value will now assume the value to be the key name.
 - **NEW**: SuperFences: if `attr_list` extension is enabled, fenced code that use brace attribute list style headers
   (` ```{lang #id .class attr=value}`) will attach arbitrary attributes that are included in the header to the code
   element.
 - **NEW**: SuperFences: when Pygments is disabled, options (such as `linenums`) included in fenced code headers no
   longer do anything. If `attr_list` is enabled, and the brace header is used, such options will be treated as HTML
   attributes. JavaScript highlighter options should be defined in the brace header form with `attr_list` enabled in
-  order to generate appropriate HTML compatible with the chosen JavaScript highlighter.
+  order to generate appropriate, compatible HTML with the chosen JavaScript highlighter.
 - **NEW**: SuperFences: backwards incompatible changes where made to custom fence API. See
- [Release Notes](./release.md#upgrading-to-80) for instructions on how to migrate to the new API.
+  [Release Notes](./release.md#upgrading-to-80) for instructions on how to migrate to the new API. Some temporary
+  support for most of the old format is in place, but is deprecated.
 - **NEW**: SuperFences: has removed legacy code tab feature. Associated `legacy_tab_classes` option has been removed.
   Please use the Tabbed extension to create general purpose tabs for code blocks or other content.
 - **NEW**: Highlight: add new option `language_prefix` which controls the prefix applied to language classes when
@@ -28,11 +30,12 @@ Please see [Release Notes](./release.md#upgrading-to-80) for details on upgradin
 - **NEW**: Highlight: option `linenums` now defaults to `None` and accepts `None`, `True`, or `False`. `None` is
   disabled by default, but can be enabled per code block. `True` enables line numbers globally. `False` disables
   globally and cannot be enabled manually per code block.
-- **FIX**: Fix issues with complex emphasis combinations in BetterEm.
 - **NEW**: ExtraRawHTML: remove extension.
+- **FIX**: Fix issues with complex emphasis combinations in BetterEm.
 - **FIX**: Details: fix corner cases related to extension and lists.
 - **FIX**: Tabbed: fix corner cases related to extension and lists.
-- **FIX**: BetterEm: Fix issues with complex emphasis combinations.
+- **FIX**: EscapeAll: Handle HTML entities special.
+- **FIX**: SuperFences: Fix parameter unpacking bug.
 
 ## 7.1
 

docs/src/markdown/about/contributing.md

@@ -1,5 +1,16 @@
 # Contributing & Support
 
+## Become a Sponsor :octicons-heart-fill-16:{: .heart-throb}
+
+Open source projects take time and money. Help support the project by becoming a sponsor. You can add your support at
+any tier you feel comfortable with. No amount is too little.
+
+:octicons-mark-github-16: [GitHub Sponsors ](https://github.com/sponsors/facelessuser)
+
+If you'd like to do a one time contribution, you can do so via PayPal.
+
+:fontawesome-brands-paypal: [PayPal](https://www.paypal.me/facelessuser)
+
 ## Bug Reports
 
 1. Please **read the documentation** and **search the issue tracker** to try and find the answer to your question

docs/src/markdown/about/release.md

@@ -2,7 +2,85 @@
 
 ## Upgrading to 8.0
 
-TODO
+One of the most invasive changes was adding the support of defining arbitrary attributes on code blocks in SuperFences
+via the brace header format. This caused numerous changes that affects those define their own custom fences. It also
+
+### SuperFences Attribute List Support
+
+SuperFences has numerous changes so that users who wish not to use Pygments can set arbitrary attributes via the brace
+header format so that can more extensively configure their code blocks for JavaScript syntax highlighters. This required
+changes to how custom fences were handled. The changes mainly affect people using custom fences. In general, people not
+defining their own custom fences will probably not notice any differences except they can now set attributes to code
+blocks now.
+
+If users are still using the legacy tab feature of SuperFences, they will find that their tabs will no longer work.
+
+- Custom fence formatters are now expected to take a new keyword attribute called `attrs`. `attrs` contains a dictionary
+  of key/value pairs defining attributes that should be attached to the main block element generated by a given
+  formatter. In general, custom formatters *should* handle these, but at the very least, they should be updated to take
+  the argument even if they don't do anything with them. If your custom fence already accepts `**kwargs`, your fence
+  should continue to work, but to apply the attributes, you will have to read the `attrs` parameter from `kwargs`.
+
+- Custom fence validators have been updated to handle validation of inputs by assigning valid inputs to either an
+  `options` dictionary or an `attrs` dictionary. The new function signature looks like
+  `#!py3 validator(language, inputs, options, attrs, md):`. Inputs should never be modified. Options should have
+  inputs added to it that configure a formatter's features while `attrs` should have all other inputs. `attrs` will only
+  be passed to a formatter when Python Markdown's [`attr_list`][attr-list] extension is enabled.
+
+    SuperFences will detect if you are using an older validator and should gracefully transition and use the old format,
+    but it is strongly recommended to use the new format.
+
+- Since attributes and options are now parsed via the [`attr_list`][attr-list] extension, custom fences can no longer
+  allow inputs in the form `key=`, they must be in the form `key`, `key="value"` or `key=value`. When defining an input
+  in the form `key` (with no value), the value will be the `key` name. To specify an empty `key`, please use `key=""`.
+
+- If a custom validator fails, SuperFences will now gracefully handle the error and try the next custom fence in the
+  queue. If a custom formatter fails, SuperFences will gracefully handle the error and abort processing the fence. If
+  you suspect your custom fence is not working, you should add your own debug code to your custom fence to verify
+  whether it is failing or not.
+
+- The tabbed feature of SuperFences has now been completely removed. Please use [Tabbed](../extensions/tabbed.md)
+  instead to create generic tabbed interfaces for code blocks and other content.
+
+### Highlight Changes
+
+Highlight added some new options to give users a little more control over code output format. Also some minor changes
+were made as a result of it now able to have arbitrary attributes passed to it that are defined by a user via
+SuperFences.
+
+- Previous versions of Highlight, when Pygments was disabled, would apply attributes to code blocks when options like
+  `linenums` were enabled. These attributes were often not helpful as they were generic and did not apply to all
+  JavaScript syntax highlighters. When Pygments is disabled, Highlight will no longer apply these unhelpful attributes
+  to code blocks, instead, if the user enables Python Markdown's `attr_list`, they can use SuperFences and define the
+  arbitrary attributes they need in the fenced code brace header, these attributes will be applied to the generated code
+  block.
+
+    For instance, if a user needed to specify the line number start with an attribute `data-linenum-start`, they could
+    simply use the brace header format to define this new attribute:
+
+    ````
+    ```{.python data-linenum-start="30"}
+    import sys
+    ```
+    ````
+
+- Custom classes, IDs, and attributes are applied to the `code` element of generated code blocks, but if a JavaScript
+  highlighter requires classes, IDs, and attributes to be applied to the `pre` element instead of the `code`
+  element, the user can enable the new option in [Highlight](../extensions/highlight.md) called `code_attr_on_pre`.
+
+- By default, JavaScript ready code blocks would normally have the specified language class prefixed with `language-`.
+  This follows the HTML 5 specification, but some highlighters may prefer something different. The prefix can now be
+  changed with the new [Highlight](../extensions/highlight.md) option called `language_prefix`.
+
+### ExtraRawHTML Removed
+
+ExtraRawHTML has officially been removed. Please use Python Markdown's [`md_in_html`][md-in-html] extension instead.
+
+### SaneHeaders Added
+
+Same headers implements Markdown headers more like CommonMark. Headers require a space after the `#` symbol in order for
+the line to be treated as a header. This allows you to use MagicLink issues at the start of a line. See
+[SaneHeaders documentation](../extensions/saneheaders.md) for more information.
 
 ## Upgrading to 7.0
 
@@ -38,7 +116,7 @@ SuperFences has deprecated `highlight_code`. This option now does nothing and wi
 If this option was used, you will have to use [custom fences](../extensions/superfences.md#custom-fences) to implement
 this behavior with your own custom formatter.
 
-### SuperFences' Attribute List Style
+### SuperFences Configurable Classes and IDs
 
 Additional classes and IDs can now be injected into fenced code blocks with the format ` ```{.lang .more-class} `.
 

docs/src/markdown/extensions/superfences.md

@@ -445,8 +445,8 @@ Format\ Function                | Description
 
 In general, formatters take five parameters: the source found between the fences, the specified language, the class name
 originally defined via the `class` option in the `custom_fence` entry, custom options, additional classes defined in
-attribute list style headers, an optional ID, any attributes defined in the attribute list style header, and the
-Markdown object (in case you want access to meta data etc.).
+brace style headers, an optional ID, any attributes defined in the brace style header, and the Markdown object (in case
+you want access to meta data etc.).
 
 ```py3
 def custom_formatter(source, language, css_class, options, md, classes=None, id_value='', attrs=None, **kwargs):
@@ -460,19 +460,19 @@ def custom_formatter(source, language, css_class, options, md, **kwargs):
     return string
 ```
 
-!!! new "New 7.0"
-    The addition of the parameters `classes` and `id_value` is new in 7.0. If injecting additional classes or ids via
-    the [attribute list style](#injecting-classes-and-ids), only then will `classes` and `id_value` be passed in to
-    preserve backwards compatibility with old custom formatters. Users, moving forward, should at the very least update
-    their formatters with `**kwargs` to future proof their custom formatters in case additional parameters are added
-    in the future.
-
 All formatters should return a string as HTML.
 
 !!! tip "YAML Configuration Format"
     If you are attempting to configure these options in a YAML based configuration (like in [MkDocs][mkdocs]), please
     see the [FAQ](../faq.md#function-references-in-yaml) to see how to specify function references in YAML.
 
+!!! new "New 7.0"
+    The addition of the parameters `classes` and `id_value` is new in 7.0. If injecting additional classes or ids via
+    [brace headers](#injecting-classes-and-ids), only then will `classes` and `id_value` be passed in to preserve
+    backwards compatibility with old custom formatters. Users, moving forward, should at the very least update their
+    formatters with `**kwargs` to future proof their custom formatters in case additional parameters are added in the
+    future.
+
 !!! new "Changes 8.0"
     Formatters now take the keyword parameter `attrs`.
 
@@ -548,7 +548,7 @@ test
         - `options`: a dictionary to which all valid options should be assigned to.
         - `attrs`: a dictionary to which all valid attributes should be assigned to.
         - `md`: the `Markdown` object.
-    - If the `attr_list` extension is enabled and the attribute list style header is used, any key/value pairs that were
+    - If the `attr_list` extension is enabled and the brace style header is used, any key/value pairs that were
       assigned as attributes by the `validator` will be passed to the `formatter`'s `attrs` parameter.
     - Options in the form of `key=` (which have no value) will are no longer be allowed. A `key` with no value will
       assume the `value` to be the `key` name. This brings consistency as options are now parsed with `attr_list`.

docs/src/scss/_general.scss

@@ -20,3 +20,45 @@
         }
     }
 }
+
+.twemoji {
+  &.heart-throb, &.heart-throb-hover {
+    svg {
+      position: relative;
+      color: #{$drac-pink};
+      animation: pulse 1.5s ease infinite;
+    }
+  }
+}
+
+@keyframes pulse {
+  0% { transform: scale(1); }
+  40% { color: #{$drac-red}; transform: scale(1.3); }
+  50% { transform: scale(1.2); }
+  60% { color: #{$drac-red}; transform: scale(1.3); }
+  100% { transform: scale(1); }
+}
+
+footer.sponsorship {
+  text-align: center;
+
+  hr {
+    display: inline-block;
+    width: px2rem(32px);
+    margin: 0 px2rem(14px);
+    vertical-align: middle;
+    border-bottom: 2px solid var(--md-default-fg-color--lighter);
+  }
+
+  &:hover {
+    hr {
+        border-color: var(--md-accent-fg-color);
+    }
+  }
+
+  &:not(:hover) {
+    .twemoji.heart-throb-hover svg{
+        color: var(--md-default-fg-color--lighter) !important;
+    }
+  }
+}

docs/src/scss/_material.scss

@@ -127,7 +127,7 @@ html {
 
   // Announcements
   [data-md-component="announce"] {
-    background-color: var(--md-primary-fg-color--transparent);
+    background-color: var(--md-default-bg-color--ultra-dark);
   }
 
   [data-md-component="announce"] .twemoji {

docs/src/scss/extensions/_admonition.scss

@@ -32,14 +32,14 @@ $new-admonitions: (
     --md-admonition-icon-color--#{$name}: #{$tint2};
 
     [data-md-color-primary^="drac-"] {
-      --md-admonition-bg-color--#{$name}: #{transparentize($tint, 0.7)};
+      --md-admonition-bg-color--#{$name}: var(--md-default-bg-color--darkest);
       --md-admonition-icon-color--#{$name}: #{$tint};
     }
   }
 
   @each $names, $tint in $old-admonitions {
     $name: nth($names, 1);
-    --md-admonition-bg-color--#{$name}: #{transparentize($tint, 0.7)};
+    --md-admonition-bg-color--#{$name}: var(--md-default-bg-color--darkest);
     --md-admonition-icon-color--#{$name}: #{$tint};
   }
 }

docs/src/scss/extensions/_highlight.scss

@@ -126,11 +126,16 @@
       margin: 0;
       padding: 0 px2em( 4px, 13.6px);
       color: var(--md-code-fg-color);
-      background-color: var(--md-code-bg-color);
+      background-color: #{$drac-bg};
       border-radius: px2rem(2px);
       box-shadow: none;
   }
 
+  .admonition-title code,
+  summary code {
+    background-color: #{tint($drac-bg, 5%)};
+  }
+
   /* Code that is also a link */
   a {
     > code {

docs/src/scss/extensions/_tables.scss

@@ -11,7 +11,7 @@
 
     th {
       color: var(--md-text-color);
-      background-color: var(--md-default-bg-color--darker);
+      background-color: var(--md-default-bg-color--darkest);
       border-bottom: px2rem(1px) solid var(--md-primary-fg-color);
 
       code {

docs/src/scss/palette/_colors.scss

@@ -35,6 +35,7 @@
   --md-default-bg-color--dark:         #{darken($drac-default-bg, 3%)};
   --md-default-bg-color--darker:       #{darken($drac-default-bg, 6%)};
   --md-default-bg-color--darkest:      #{darken($drac-default-bg, 9%)};
+  --md-default-bg-color--ultra-dark:   #{darken($drac-default-bg, 15%)};
 }
 
 // ----------------------------------------------------------------------------

docs/theme/announce.html

@@ -0,0 +1,9 @@
+<span class="twemoji">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M23 12l-2.44-2.78.34-3.68-3.61-.82-1.89-3.18L12 3 8.6 1.54 6.71 4.72l-3.61.81.33.68L1 12l2.44 2.78-.34 3.69 3.61.82 1.89 3.18L12 21l3.4 1.46 1.89-3.18 3.61-.82-.34-3.68L23 12m-10 5h-2v-2h2v2m0-4h-2V7h2v6z"></path></svg></span>
+  8.0 has been released! Check out the <a href="about/release/#upgrade-to-80">Release Notes</a> for more information and migration tips.
+<br>
+<a href="{{ 'about/contributing/#contributing--support' | url }}">Sponsorship</a>
+is now available!
+<span class="twemoji heart-throb">
+  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M7.655 14.916L8 14.25l.345.666a.752.752 0 01-.69 0zm0 0L8 14.25l.345.666.002-.001.006-.003.018-.01a7.643 7.643 0 00.31-.17 22.08 22.08 0 003.433-2.414C13.956 10.731 16 8.35 16 5.5 16 2.836 13.914 1 11.75 1 10.203 1 8.847 1.802 8 3.02 7.153 1.802 5.797 1 4.25 1 2.086 1 0 2.836 0 5.5c0 2.85 2.045 5.231 3.885 6.818a22.075 22.075 0 003.744 2.584l.018.01.006.003h.002z"/></svg>
+</span>

docs/theme/main.html

@@ -0,0 +1,16 @@
+{% extends "base.html" %}
+
+{% block announce %}{% include "announce.html" ignore missing %}{% endblock %}
+
+{% block content %}
+  {{ super() }}
+  <footer class="sponsorship">
+    <hr>
+    <a href="https://github.com/sponsors/facelessuser" title="Become a sponsor">
+      <span class="twemoji heart-throb-hover">
+        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M7.655 14.916L8 14.25l.345.666a.752.752 0 01-.69 0zm0 0L8 14.25l.345.666.002-.001.006-.003.018-.01a7.643 7.643 0 00.31-.17 22.08 22.08 0 003.433-2.414C13.956 10.731 16 8.35 16 5.5 16 2.836 13.914 1 11.75 1 10.203 1 8.847 1.802 8 3.02 7.153 1.802 5.797 1 4.25 1 2.086 1 0 2.836 0 5.5c0 2.85 2.045 5.231 3.885 6.818a22.075 22.075 0 003.744 2.584l.018.01.006.003h.002z"/></svg>
+      </span>
+    </a>
+    <hr>
+  </footer>
+{% endblock %}

mkdocs.yml

@@ -136,7 +136,7 @@ extra:
     - icon: fontawesome/brands/discord
       link: https://discord.gg/TWs8Tgr
 extra_css:
-  - assets/pymdownx-extras/extra-b28603fe0d.css
+  - assets/pymdownx-extras/extra-21f29ce7c5.css
 extra_javascript:
   - assets/pymdownx-extras/extra-835d408546.js