Add Markdown renderer as superfences formatter

.github/pull_request_template.md

@@ -10,6 +10,6 @@
 - [ ] This PR follows the [contribution guidelines](https://python-markdown.github.io/contributing/).
 - [ ] The code follows the [Code Style Guide](https://python-markdown.github.io/contributing/#code-style-guide).
 - [ ] The commit message follows the [Commit Message Style Guide](https://python-markdown.github.io/contributing/#commit-message-style-guide).
-- [ ] I have added or updated relevant docs, including release notes if applicable which follow the [Documentation Style Guide](Documentation Style Guide).
+- [ ] I have added or updated relevant docs, including release notes if applicable which follow the [Documentation Style Guide](https://python-markdown.github.io/contributing/#documentation-style-guide).
 - [ ] I have added or updated relevant tests.
 - [ ] I have not requested, and will not request, an automated AI review for this PR. <!-- You are welcome to do so in your own fork. -->

MANIFEST.in

@@ -6,7 +6,7 @@ include LICENSE.md
 include README.md
 include INSTALL.md
 include MANIFEST
-include *-requirements.txt
 include mkdocs.yml
 include tox.ini
-include scripts/*.py
+recursive-include .zensical *.jinja *.py *.ico *.png *.svg *.css *.html
+include tools/*.py

docs/contributing.md

@@ -214,10 +214,12 @@ want to use your editor's tools to automatically hard wrap lines of text.
 Don't use abbreviations such as 'e.g.' but instead use the long form, such as
 'For example'.
 
-The documentation is built from the [Markdown] source files in the [`docs`
-directory][docs directory] by the [MkDocs] static site generator. In addition to
-the basic Markdown syntax, the following extensions are supported: [extra],
-[admonition], [smarty], [codehilite], and [toc].
+The documentation is built from the [Markdown] source files in the
+[`docs` directory][docs directory] by the [Zensical] static site generator.
+In addition to the basic Markdown syntax, the following extensions are
+supported: [abbr], [admonition], [attr_list], [def_list], [footnotes],
+[md_in_html], [smarty], [toc], [mdx_gh_links], [pymdownx.highlight], and
+[pymdownx.superfences].
 
 There are a few conventions you should follow when working on the
 documentation.
@@ -226,13 +228,13 @@ documentation.
 
 Headers should use the hash style. For example:
 
-```md
+``` markdown
 ## Some important topic
 ```
 
 The underline style should not be used. Don't do this:
 
-```md
+``` markdown
 Some important topic
 ====================
 ```
@@ -242,12 +244,12 @@ Some important topic
 Links should always use the reference style, with the referenced hyperlinks kept
 at the end of the document.
 
-```md
-Here is a link to [some other thing][other-thing].
+``` markdown
+Here is a link to [some other thing].
 
 More text...
 
-[other-thing]: http://example.com/other/thing
+[some other thing]: http://example.com/other/thing
 ```
 
 This style helps keep the documentation source consistent and readable.
@@ -257,26 +259,135 @@ you should use a relative link, and link to the `.md` suffix. If applicable, it
 is preferred that the link includes a hash fragment pointing to the specific
 section of the page. For example:
 
-```md
-[authentication]: reference.md#Markdown
+``` markdown
+[authentication]: somepage.md#auth
 ```
 
 Linking in this style ensures that the links work when browsing the
 documentation on GitHub. If your Markdown editor makes links clickable, they
 will work there as well. When the documentation is built, these links will be
 converted into regular links which point to the built HTML pages.
 
+When linking to the objects in the [API documentation], simply use a reference
+to the dot path of the Python object. There is no need to define the
+reference as it is already predefined in a collection of global link
+references.
+
+``` markdown
+[`markdown.Markdown`][markdown.Markdown]
+```
+
+Note that as the link label contains code, it should be wrapped in a code span
+and the reference needs to be defined immediately after. This also allows a
+long dot path to be truncated for simplicity in the text.
+
+``` markdown
+[`someobject`][long.dot.path.to.someobject]
+```
+
 #### Notes and Warnings
 
 If you want to draw attention to a note or warning, use the syntax defined in
 Python-Markdown's [Admonition Extension]:
 
-```md
+``` markdown
 !!! note
 
     This is the content of the note.
 ```
 
+In addition to the [supported types] listed in Zensical's documentation, the
+`seealso` type is supported.
+
+``` markdown
+!!! seealso "See Also"
+
+    This should link to some relevant content contained elsewhere.
+```
+
+Unlike the other defined types, `seealso` needs the title to be manually
+defined as the default behavior will not split a generated title into two
+words.
+
+!!! seealso "See Also"
+
+    See Zensical's documentation on [supported types] for more information.
+
+#### Code Blocks
+
+All code blocks should use the fenced code block style. If a code block is
+demonstrating Markdown syntax, if can be assigned the `md-render` attribute,
+and both the Markdown source and HTML output will be rendered in a nested set
+of code blocks.
+
+```` markdown
+``` md-render
+Some *Markdown* text.
+```
+````
+
+The above code block will be rendered at follows:
+
+``` md-render
+Some *Markdown* text.
+```
+
+The rendered output is generated by an isolated Markdown instance, which is
+separate from the body text of the document. Extensions and configuration
+options are not carried over. If extension(s) need to be enabled for the code
+block, then they can be defined as YAML front-matter within the code block.
+The `extensions` and `extension_configs` keywords are the only options which
+are passed on to the isolated Markdown instance.The YAML front-matter is
+stripped from the body of the code block before the code block is passing to
+the isolated Markdown instance.
+
+```` markdown
+``` md-render
+---
+extensions: [toc]
+extension_configs:
+    toc:
+        permalinks: true
+---
+# A Markdown header
+```
+````
+
+The above code block would be rendered with the `toc` extension and that
+extension's `permalinks` option enabled as follows:
+
+``` md-render
+---
+extensions: [toc]
+extension_configs:
+    toc:
+        permalink: true
+---
+# A Markdown header
+```
+
+Note that the YAML front-matter must be deliminated by a line of at least three
+hyphens (both before and after) and be valid YAML. Any invalid formatting or
+unknown keywords will cause the entire block to not be recognized as a code
+block. Therefore, be sure to confirm the formatting before submitting
+proposed changes which utilize rendered code blocks.
+
+If a Markdown code block should not receive the special rendering described
+above, then simply assign it the `markdown` attribute. It will then be
+rendered as a normal Markdown code block.
+
+```` markdown
+``` markdown
+Some *Markdown* text.
+```
+````
+
+The above code block would render as follows:
+
+``` markdown
+Some *Markdown* text.
+```
+
 #### Changelog
 
 Any commit/pull request which changes the behavior of the Markdown library in
@@ -622,13 +733,21 @@ for details.
 [Flake8]: http://flake8.pycqa.org/en/latest/index.html
 [Markdown]: https://daringfireball.net/projects/markdown/basics
 [docs directory]: https://github.com/Python-Markdown/markdown/tree/master/docs
-[MkDocs]: https://www.mkdocs.org/
-[extra]: extensions/extra.md
+[Zensical]: https://zensical.org/
+[abbr]: extensions/abbreviations.md
 [admonition]: extensions/admonition.md
+[attr_list]: extensions/attr_list.md
+[def_list]: extensions/definition_lists.md
+[footnotes]: extensions/footnotes.md
+[md_in_html]: extensions/md_in_html.md
 [smarty]: extensions/smarty.md
-[codehilite]: extensions/code_hilite.md
 [toc]: extensions/toc.md
+[mdx_gh_links]: https://github.com/Python-Markdown/github-links
+[pymdownx.highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+[pymdownx.superfences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+[API documentation]:reference/markdown.md
 [Admonition Extension]: extensions/admonition.md#syntax
+[supported types]: https://zensical.org/docs/authoring/admonitions/#supported-types
 [fork]: https://help.github.com/articles/about-forks
 [cloning your fork]: https://help.github.com/articles/cloning-a-repository/
 [configure a remote]: https://help.github.com/articles/configuring-a-remote-for-a-fork

docs/extensions/abbreviations.md

@@ -34,23 +34,19 @@ Abbreviations are defined using the syntax established in
 
 [php]: http://www.michelf.com/projects/php-markdown/extra/#abbr
 
-Thus, the following text (taken from the above referenced PHP documentation):
+For example, consider the following text (taken from the above referenced PHP documentation).
 
-```md
+``` md-render
+---
+extensions: [abbr]
+---
 The HTML specification
 is maintained by the W3C.
 
 *[HTML]: Hyper Text Markup Language
 *[W3C]:  World Wide Web Consortium
 ```
 
-will be rendered as:
-
-```html
-<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification
-is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>
-```
-
 The backslash (`\`) is not permitted in an abbreviation. Any abbreviation
 definitions which include one or more backslashes between the square brackets
 will not be recognized as an abbreviation definition.
@@ -78,7 +74,14 @@ Disabling Abbreviations
 When using the `glossary` option, there may be times when you need to turn off
 a specific abbreviation. To do this, set the abbreviation to `''` or `""`.
 
-```md
+``` md-render
+---
+extensions: [abbr]
+extension_configs:
+    abbr:
+        glossary:
+            HTML: Hyper Text Markup Language
+---
 The HTML abbreviation is disabled on this page.
 
 *[HTML]: ''

docs/extensions/admonition.md

@@ -35,78 +35,58 @@ Syntax
 
 Admonitions are created using the following syntax:
 
-```md
+``` md-render
+---
+extensions: [admonition]
+---
 !!! type "optional explicit title within double quotes"
     Any number of other indented markdown elements.
 
     This is the second paragraph.
 ```
 
 `type` will be used as the CSS class name and as default title. It must be a
-single word. So, for instance:
+single word.
 
-```md
+``` md-render
+---
+extensions: [admonition]
+---
 !!! note
     You should note that the title will be automatically capitalized.
 ```
 
-will render:
-
-```html
-<div class="admonition note">
-<p class="admonition-title">Note</p>
-<p>You should note that the title will be automatically capitalized.</p>
-</div>
-```
+Optionally, you can use custom titles.
 
-Optionally, you can use custom titles. For instance:
-
-```md
+``` md-render
+---
+extensions: [admonition]
+---
 !!! danger "Don't try this at home"
     ...
 ```
 
-will render:
-
-```html
-<div class="admonition danger">
-<p class="admonition-title">Don't try this at home</p>
-<p>...</p>
-</div>
-```
-
-If you don't want a title, use a blank string `""`:
+If you don't want a title, use a blank string `""`.
 
-```md
+``` md-render
+---
+extensions: [admonition]
+---
 !!! important ""
     This is an admonition box without a title.
 ```
 
-results in:
-
-```html
-<div class="admonition important">
-<p>This is an admonition box without a title.</p>
-</div>
-```
-
 You can also provide additional CSS class names separated by spaces. The first
-class should be the "type." For example:
+class should be the "type."
 
-```md
+``` md-render
+---
+extensions: [admonition]
+---
 !!! danger highlight blink "Don't try this at home"
     ...
 ```
 
-will render:
-
-```html
-<div class="admonition danger highlight blink">
-<p class="admonition-title">Don't try this at home</p>
-<p>...</p>
-</div>
-```
-
 rST suggests the following "types": `attention`, `caution`, `danger`, `error`,
 `hint`, `important`, `note`, `tip`, and `warning`; however, you're free to use
 whatever you want.