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 %}

.zensical/theme/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);
+}

.zensical/theme/partials/copyright.html

@@ -0,0 +1,48 @@
+<!--
+  Copyright (c) 2025-2026 Zensical and contributors
+
+  SPDX-License-Identifier: MIT
+  Third-party contributions licensed under DCO
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Copyright and theme information -->
+<div class="md-copyright">
+  {% if config.copyright %}
+    <div class="md-copyright__highlight">
+      {{ config.copyright }}
+    </div>
+  {% endif %}
+  {% if not config.extra.generator == false %}
+    Made with
+    <a
+      href="https://zensical.org/"
+      target="_blank" rel="noopener"
+    >Zensical</a>,
+    <a
+      href="{{ config.site_url }}"
+      target="_blank" rel="noopener"
+    >{{ config.site_name }}</a>, and
+    <a
+      href="https://facelessuser.github.io/pymdown-extensions/"
+      target="_blank" rel="noopener"
+    >PyMdown Extensions</a>.
+  {% endif %}
+</div>

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