Switch docs to Zensical

.github/workflows/deploy.yml

@@ -74,7 +74,7 @@ jobs:
       - name: Build
         run: |
           cd md
-          python -m mkdocs build --clean --verbose
+          python -m zensical build --clean
       - name: Publish
         if: success()
         run: |

.github/workflows/manual_deploy.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Build
         run: |
           cd md
-          python -m mkdocs build --clean --verbose
+          python -m zensical build --clean
       - name: Publish
         if: success()
         run: |

docs/templates/python/nature/attribute.html.jinja → .zensical/mkdocstring_templates/python/material/attribute.html.jinja

@@ -1,7 +1,7 @@
 {% extends "_base/attribute.html.jinja" %}
 
 {% block heading scoped %}
-  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ attribute.relative_filepath }}#L{{ attribute.lineno }}{% if attribute.endlineno > attribute.lineno %}-L{{ attribute.endlineno }}{% endif %}" title='View source code on GitHub'>&lsaquo;&rsaquo;</a>
+  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ attribute.relative_filepath }}#L{{ attribute.lineno }}{% if attribute.endlineno > attribute.lineno %}-L{{ attribute.endlineno }}{% endif %}" target="_blank" title="{{ config.extra.source.title }}"></a>
   {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
   {%+ filter highlight(language="python", inline=True) %}
     {{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}

docs/templates/python/nature/class.html.jinja → .zensical/mkdocstring_templates/python/material/class.html.jinja

@@ -1,6 +1,6 @@
 {% extends "_base/class.html.jinja" %}
 
 {% block heading scoped %}
-  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ class.relative_filepath }}#L{{ class.lineno }}" title="{{ config.extra.source.title }}">&lsaquo;&rsaquo;</a>
+  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ class.relative_filepath }}#L{{ class.lineno }}" target="_blank" title="{{ config.extra.source.title }}"></a>
   {{ super() }}
 {% endblock heading %}

docs/templates/python/nature/function.html.jinja → .zensical/mkdocstring_templates/python/material/function.html.jinja

@@ -1,6 +1,6 @@
 {% extends "_base/function.html.jinja" %}
 
 {% block heading scoped %}
-  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ function.relative_filepath }}#L{{ function.lineno }}{% if function.endlineno > function.lineno %}-L{{ function.endlineno }}{% endif %}" title="{{ config.extra.source.title }}">&lsaquo;&rsaquo;</a>
+  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ function.relative_filepath }}#L{{ function.lineno }}{% if function.endlineno > function.lineno %}-L{{ function.endlineno }}{% endif %}" target="_blank" title="{{ config.extra.source.title }}"></a>
   {{ super() }}
 {% endblock heading %}

docs/templates/python/nature/module.html.jinja → .zensical/mkdocstring_templates/python/material/module.html.jinja

@@ -1,6 +1,6 @@
 {% extends "_base/module.html.jinja" %}
 
 {% block heading scoped %}
-  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ module.relative_filepath }}" title="{{ config.extra.source.title }}">&lsaquo;&rsaquo;</a>
+  <a class="doc-source-link" href="{{ config.extra.source.repo }}/tree/{{ config.extra.source.tag }}/{{ module.relative_filepath }}" target="_blank" title="{{ config.extra.source.title }}"></a>
   {{ super() }}
 {% endblock heading %}

docs/assets/stylesheets/mkdocstrings.css

@@ -0,0 +1,108 @@
+/* Highlight the bottom border of the active menu item. */
+.md-tabs .md-tabs__item--active {
+    border-bottom: .1rem solid var(--md-accent-fg-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+  height: 1em;
+  width: 1em;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+/* Code spans in tables. */
+
+table code {
+  background-color: transparent !important;
+}
+
+/* Style headings */
+.doc-heading {
+  background: var(--md-accent-fg-color--transparent);
+  border-radius: .4rem;
+  padding: .35rem .8rem;
+}
+
+.doc-heading code {
+  background: transparent;  
+}
+
+/* Customize labels. */
+.doc-label>code {
+  background-color: var(--md-code-bg-color);
+  border: 1px solid var(--md-default-fg-color);
+  border-radius: 15px;
+  padding: 2px 1em;
+  text-wrap: nowrap;
+}
+
+.doc-label-deprecated>code {
+  background-color: #ff91001a;
+  border-color: #ff9100;
+}
+
+/* Style source links */
+a.doc-source-link {
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-square-code-icon lucide-square-code"><path d="m10 9-3 3 3 3"/><path d="m14 15 3-3-3-3"/><rect x="3" y="3" width="18" height="18" rx="2"/></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-square-code-icon lucide-square-code"><path d="m10 9-3 3 3 3"/><path d="m14 15 3-3-3-3"/><rect x="3" y="3" width="18" height="18" rx="2"/></svg>');
+  mask-position: center;
+  mask-repeat: no-repeat;
+  display: inline-block;
+  height: 1.5rem;
+  width: 1.5rem;
+  position: relative;
+  float: right;
+  margin-left: .5rem;
+  background-color: var(--md-default-fg-color--lighter);
+}
+
+a.doc-source-link:hover {
+  background-color: var(--md-accent-fg-color);
+  text-decoration: none;
+}
+
+h1 a.doc-source-link {
+  mask-position: bottom;
+}
+
+.md-tooltip2 a.doc-source-link {
+  display: none;
+}
+
+/* Reposiiton content.action.edit and content.action.view page buttons */
+[dir=ltr] .md-content__button {
+    position: relative;
+    top: -3.5em;
+}
+
+/* Add support for `seealso` Admonition */
+.md-typeset .admonition.seealso {
+    background-color: var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset .seealso>.admonition-title:before {
+    background-color: var(--md-accent-fg-color);
+}
+
+.md-typeset .seealso>.admonition-title:after {
+    color: var(--md-accent-fg-color);
+}
+
+.md-typeset .seealso>.admonition-title:before {
+    --md-admonition-icon--seealso: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-square-arrow-out-up-right-icon lucide-square-arrow-out-up-right"><path d="M21 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h6"/><path d="m21 3-9 9"/><path d="M15 3h6v6"/></svg>');
+    -webkit-mask-image: var(--md-admonition-icon--seealso);
+    mask-image: var(--md-admonition-icon--seealso);
+}

docs/authors.md

@@ -1,4 +1,6 @@
+---
 title: Authors
+---
 
 Primary Authors
 ===============

docs/change_log/release-2.1.md

@@ -32,7 +32,7 @@ release, there are a few backward-incompatible changes to note:
   wrapper methods. It now expects keyword arguments. Currently, the positional
   arguments should continue to work, but the solution feels hacky and may be
   removed in a future version. All users are encouraged to use keyword arguments
-  as documented in the [Library Reference](../reference.md).
+  as documented in the [Library Reference](../library.md).
 
 * Past versions of Python-Markdown provided module level Global variables which
   controlled the behavior of a few different aspects of the parser. Those global
@@ -41,7 +41,7 @@ release, there are a few backward-incompatible changes to note:
   initializing a class instance. Therefore, if you were editing the global
   variables (either by editing the source or by overriding them in your code),
   you should now set them on the class. See the [Library
-  Reference](../reference.md) for the options available.
+  Reference](../library.md) for the options available.
 
 * If you have been using the HeaderId extension to
   define custom ids on headers, you will want to switch to using the new

docs/change_log/release-2.5.md

@@ -14,8 +14,6 @@ Backwards-incompatible Changes
 * Python-Markdown no longer supports Python version 2.6. You must be using Python
   versions 2.7, 3.2, 3.3, or 3.4.
 
-[importlib]: https://pypi.org/project/importlib/
-
 * The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated**
   and will raise a `KeyError` if provided. In the previous release (2.4), it was
   issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used
@@ -96,14 +94,14 @@ Backwards-incompatible Changes
 
         $ python -m markdown -x markdown.extensions.extra input.txt
 
-    See the [documentation](../reference.md#extensions) for a full explanation
+    See the [documentation](../library.md#extensions) for a full explanation
     of the current behavior.
 
 * The previously documented method of appending the extension configuration as
   a string to the extension name will be deprecated in Python-Markdown
   version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The
-  [`extension_configs`](../reference.md#extension_configs) keyword should
-  be used instead. See the [documentation](../reference.md#extension_configs)
+  [`extension_configs`](../library.md#extension_configs) keyword should
+  be used instead. See the [documentation](../library.md#extension_configs)
   for a full explanation of the current behavior.
 
 What's New in Python-Markdown 2.5
@@ -146,7 +144,7 @@ What's New in Python-Markdown 2.5
     `makeExtension` function included in the module. Extension authors will want
     to document carefully what is required to load their extensions.
 
-[ex]: ../reference.md#extensions
+[ex]: ../library.md#extensions
 
 * The Extension Configuration code has been refactored to make it a little
   easier for extension authors to work with configuration settings. As a
@@ -160,7 +158,7 @@ What's New in Python-Markdown 2.5
     their code going forward. The included extensions provide a model for best
     practices. See the [API] documentation for a full explanation.
 
-[ec]: ../reference.md#extension_configs
+[ec]: ../library.md#extension_configs
 [API]: ../extensions/api.md#configsettings
 
 * The [Command Line Interface][cli] now accepts a `--extensions_config` (or

docs/change_log/release-2.6.md

@@ -128,16 +128,16 @@ markdown.markdown(text, extensions=['mdx_math'])
 Extension authors will want to update their documentation to reflect the new
 behavior.
 
-See the [documentation](../reference.md#extensions) for a full explanation
+See the [documentation](../library.md#extensions) for a full explanation
 of the current behavior.
 
 ### Extension Configuration as Part of Extension Name Deprecated
 
 The previously documented method of appending the extension configuration
 options as a string to the extension name is deprecated and will raise a
 **`DeprecationWarning`** in version 2.6 and an error in 2.7. The
-[`extension_configs`](../reference.md#extension_configs) keyword should be used
-instead. See the [documentation](../reference.md#extension_configs) for a full
+[`extension_configs`](../library.md#extension_configs) keyword should be used
+instead. See the [documentation](../library.md#extension_configs) for a full
 explanation of the current behavior.
 
 ### HeaderId Extension Pending Deprecation

docs/changelog.md

@@ -1,5 +1,7 @@
+---
 title: Changelog
 toc_depth: 2
+---
 
 # Python-Markdown Changelog
 
@@ -792,15 +794,15 @@ See the [Contributing Guide](contributing.md) for details.
     for each specific extension to find the assigned name.
 
     If an extension does not define an entry point, then the full path to the
-    extension must be used. See the [documentation](reference.md#extensions) for
+    extension must be used. See the [documentation](library.md#extensions) for
     a full explanation of the current behavior.
 
 * Extension configuration as part of extension name deprecated
 
     The previously documented method of appending the extension configuration
     options as a string to the extension name is deprecated and will raise an error.
-    The [`extension_configs`](reference.md#extension_configs) keyword should be
-    used instead. See the [documentation](reference.md#extension_configs) for a
+    The [`extension_configs`](library.md#extension_configs) keyword should be
+    used instead. See the [documentation](library.md#extension_configs) for a
     full explanation of the current behavior.
 
 * HeaderId extension deprecated

docs/cli.md

@@ -1,4 +1,6 @@
+---
 title: Command Line
+---
 
 Using Python-Markdown on the Command Line
 =========================================
@@ -154,11 +156,10 @@ The `--extension_configs` option will only support YAML configuration files if
 [PyYAML] is installed on your system. JSON should work with no additional
 dependencies. The format of your configuration file is automatically detected.
 
-[ec]: reference.md#extension_configs
+[ec]: library.md#extension_configs
 [YAML]: https://yaml.org/
 [JSON]: https://json.org/
 [PyYAML]: https://pyyaml.org/
-[2.5 release notes]: change_log/release-2.5.md
 
 ## Using the `markdown_py` Command
 
@@ -201,7 +202,7 @@ path.
     markdown text files will not likely be in that directory, so it is much
     more convenient to have `markdown_py` on your path.
 
-!!!Note
+!!! tip
     Python-Markdown uses `"markdown_py"` as a script name because the Perl
     implementation has already taken the more obvious name "markdown".
     Additionally, the default Python configuration on some systems would cause a

docs/contributing.md

@@ -148,7 +148,7 @@ repeatedly opens unproductive issues or requests, they may be blocked from
 contributing to the project as it is disruptive and disrespectful of the
 maintainers' time.
 
-!!! Note
+!!! info
     This policy was largely inspired by the Astropy Project's 
     [Usage of Generative AI] policy.
 
@@ -411,7 +411,7 @@ coverage run --source=markdown -m unittest discover tests
 coverage report --show-missing
 ```
 
-!!! note
+!!! tip
 
     Some tests require the [PyTidyLib] library, which depends on the [HTML Tidy]
     library. If you do not have PyTidyLib installed, the tests which depend upon
@@ -436,7 +436,7 @@ pip install tox
 Then, to run all configured test environments, simply call the command `tox`
 with no arguments. See help (`tox -h`) for more options.
 
-!!! note
+!!! tip
 
     The tox environments expect that some dependencies are already installed on
     your system. For example, by default, any Python version specific
@@ -523,7 +523,7 @@ following steps:
 
         Bump version to X.X.X
 
-    !!! note 
+    !!! tip
 
         For the checks to run properly the `release`{ .label .release } label
         must be set on GitHub before creating the pull request. If the label

docs/extensions/abbreviations.md

@@ -1,4 +1,6 @@
+---
 title: Abbreviations Extension
+---
 
 Abbreviations
 =============
@@ -11,7 +13,7 @@ Specifically, any defined abbreviation is wrapped in  an `<abbr>` tag.
 
 The Abbreviations extension is included in the standard Markdown library.
 
-!!! Note
+!!! info "Note"
 
     This extension is in __maintenance mode__.  We will continue to fix bugs
     and keep it up-to-date with the core parser, but no new features or

docs/extensions/admonition.md

@@ -1,4 +1,6 @@
+---
 title: Admonition Extension
+---
 
 Admonition
 ==========
@@ -12,7 +14,7 @@ This extension is included in the standard Markdown library.
 
 [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions
 
-!!! Note
+!!! info "Note"
 
     This extension is in __maintenance mode__.  We will continue to fix bugs
     and keep it up-to-date with the core parser, but no new features or