diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3ad524fb..67885c57 100644 --- a/.github/pull_request_template.md +++ b/.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. diff --git a/MANIFEST.in b/MANIFEST.in index f95e25e5..8e5caeaa 100644 --- a/MANIFEST.in +++ b/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 diff --git a/docs/contributing.md b/docs/contributing.md index 0923a9db..ead5145c 100644 --- a/docs/contributing.md +++ b/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,8 +259,8 @@ 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 @@ -266,17 +268,126 @@ 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 diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md index 95f95f86..feb67f3c 100644 --- a/docs/extensions/abbreviations.md +++ b/docs/extensions/abbreviations.md @@ -34,9 +34,12 @@ 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. @@ -44,13 +47,6 @@ is maintained by the W3C. *[W3C]: World Wide Web Consortium ``` -will be rendered as: - -```html -
The HTML specification -is maintained by the W3C.
-``` - 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]: '' diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md index f2969775..dd96d662 100644 --- a/docs/extensions/admonition.md +++ b/docs/extensions/admonition.md @@ -35,7 +35,10 @@ 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. @@ -43,70 +46,47 @@ Admonitions are created using the following syntax: ``` `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 -Note
-You should note that the title will be automatically capitalized.
-Don't try this at home
-...
-This is an admonition box without a title.
-Don't try this at home
-...
-This is a paragraph.
+{ #an_id .a_class } ``` An exception is headers, as they are only ever allowed on one line. -```text -A setext style header {: #setext} +``` md-render +--- +extensions: [attr_list] +--- +A setext style header { #setext} ================================= -### A hash style header ### {: #hash } -``` - -The above results in the following output: - -```html -| set on td | -set on em | -
|---|---|
| a | -b | -
` tags and output.
-```md
- # Code goes here ...
-```
-
-Will result in:
-
+``` md-render
+---
+extensions: [codehilite]
+---
# Code goes here ...
-
-Lets see the source for that:
-
-```html
-# Code goes here ...
-
```
!!! tip
diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md
index c33341b2..7abd8fbc 100644
--- a/docs/extensions/definition_lists.md
+++ b/docs/extensions/definition_lists.md
@@ -37,9 +37,12 @@ Definition lists are defined using the syntax established in
[php]: http://www.michelf.com/projects/php-markdown/extra/#def-list
-Thus, the following text (taken from the above referenced PHP documentation):
+Consider the following text taken from the above referenced PHP documentation.
-```md
+``` md-render
+---
+extensions: [def_list]
+---
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
@@ -48,19 +51,6 @@ Orange
: The fruit of an evergreen tree of the genus Citrus.
```
-will be rendered as:
-
-```html
-HTML Document
``` @@ -118,19 +136,15 @@ be prefixed with a dot and not contain any whitespace (`.language-name`). So long as the language is the only option specified, the curly brackets and/or the dot may be excluded: -````md +```` md-render +--- +extensions: [fenced_code] +--- ``` htmlHTML Document
``` ```` -Either of the above examples will output the following HTML: - -```html -<p>HTML Document</p>
-
-```
-
Note that the language name has been prefixed with `language-` and it has been assigned to the `class` attribute on
the `` tag, which is the format suggested by the [HTML 5 Specification][html5] (see the second "example" in the
Specification). While `language` is the default prefix, the prefix may be overridden using the
@@ -140,7 +154,10 @@ Specification). While `language` is the default prefix, the prefix may be overri
In addition to the language, additional classes may be defined by prefixing them with a dot, just like the language.
-````md
+```` md-render
+---
+extensions: [fenced_code]
+---
``` { .html .foo .bar }
HTML Document
```
@@ -150,37 +167,31 @@ When defining multiple classes, only the first class will be used as the "langua
assigned to the `` tag unaltered. Additionally, the curly braces and dot are required for all classes, including
the language class if more than one class is defined.
-The above example will output the following HTML:
-
-```html
-<p>HTML Document</p>
-
-```
-
#### ID
An `id` can be defined for a code block, which would allow a link to point directly to the code block using a URL
hash. IDs must be prefixed with a hash character (`#`) and only contain characters permitted in HTML `id` attributes.
-````md
+```` md-render
+---
+extensions: [fenced_code]
+---
``` { #example }
A linkable code block
```
````
-The `id` attribute is assigned to the `` tag of the output. The above example will output the following HTML:
-
-```html
-A linkable code block
-
-```
-
-From elsewhere within the same document, one could link to the code block with `[link](#example)`.
+The `id` attribute is assigned to the `` tag of the output. From
+elsewhere within the same document, one could link to the code block with `
+[link](#example)`.
IDs may be defined along with the language, other classes, or any other supported attributes. The order of items does
not matter.
-````md
+```` md-render
+---
+extensions: [fenced_code]
+---
``` { #example .lang .foo .bar }
A linkable code block
```
@@ -193,19 +204,15 @@ the attribute list. So long as code highlighting is not enabled (see below), the
attributes on the `` tag in the output. Key/value pairs must be defined using the syntax documented for the
`attr_list` extension (for example, values with whitespace must be wrapped in quotes).
-````md
+```` md-render
+---
+extensions: [fenced_code, attr_list]
+---
``` { .lang #example style="color: #333; background: #f8f8f8;" }
A code block with inline styles. Fancy!
```
````
-The above example will output the following HTML:
-
-```html
-A code block with inline styles. Fancy!
-
-```
-
If the `attr_list` extension is not enabled, then the key/value pairs will be ignored.
#### Syntax Highlighting
@@ -218,9 +225,12 @@ language guessing is not disabled for the `codehilite` extension, then the langu
The `codehilite` extension uses the [Pygments] engine to do syntax highlighting. Any valid Pygments options can be
defined as key/value pairs in the attribute list and will be passed on to Pygments.
-````md
-``` { .lang linenos=true linenostart=42 hl_lines="43-44 50" title="An Example Code Block" }`
-A truncated code block...
+```` md-render
+---
+extensions: [fenced_code, codehilite, attr_list]
+---
+``` { .python linenos=true linenostart=42 hl_lines="43-44 50" title="An Example Code Block" }
+# A code block...
```
````
diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md
index 080e3e4a..fb65cada 100644
--- a/docs/extensions/footnotes.md
+++ b/docs/extensions/footnotes.md
@@ -38,7 +38,10 @@ the output.
Example:
-```md
+``` md-render
+---
+extensions: [footnotes]
+---
Footnotes have a name, a reference[^1], and a definition[^word].
[^1]: This is a footnote definition.
diff --git a/docs/extensions/legacy_attrs.md b/docs/extensions/legacy_attrs.md
index 8873987f..510f0ede 100644
--- a/docs/extensions/legacy_attrs.md
+++ b/docs/extensions/legacy_attrs.md
@@ -37,36 +37,31 @@ assign the attributes to:
For example, to define a class to a paragraph:
-```md
+``` md-render
+---
+extensions: [legacy_attrs]
+---
A paragraph with the attribute defined {@class=foo}anywhere within.
```
-Which results in the following output:
-
-```html
-A paragraph with the attribute defined anywhere within.
-```
-
The same applies for inline elements:
-```md
+``` md-render
+---
+extensions: [legacy_attrs]
+---
Some *emphasized{@id=bar}* text.
```
-```html
-Some emphasized text.
-```
-
You can also define attributes in images:
-```md
+``` md-render
+---
+extensions: [legacy_attrs]
+---

```
-```html
-
-```
-
## Usage
See [Extensions](index.md) for general extension usage. Use `legacy_attrs` as the
diff --git a/docs/extensions/md_in_html.md b/docs/extensions/md_in_html.md
index a3a2dccb..13a9a88b 100644
--- a/docs/extensions/md_in_html.md
+++ b/docs/extensions/md_in_html.md
@@ -48,41 +48,31 @@ The following tags have the `block` behavior by default: `article`, `aside`, `bl
`iframe`, `main`, `map`, `menu`, `nav`, `noscript`, `object`, `ol`, `output`, `progress`, `section`, `table`,
`tbody`, `tfoot`, `thead`, `tr`, `ul` and `video`.
-For example, the following:
+For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
This is a *Markdown* Paragraph.
```
-... is rendered as:
-
-``` html
-
-This is a Markdown Paragraph.
-
-```
-
The following tags have the `span` behavior by default: `address`, `dd`, `dt`, `h[1-6]`, `legend`, `li`, `p`, `td`,
and `th`.
-For example, the following:
+For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
This is not a *Markdown* Paragraph.
```
-... is rendered as:
-
-``` html
-
-This is not a Markdown Paragraph.
-
-```
-
### `markdown="block"` { #block }
When the `markdown` attribute is set to `"block"`, then the parser will force the `block` behavior on the contents of
@@ -91,9 +81,12 @@ the element so long as it is one of the `block` or `span` tags.
The content of a `block` element is parsed into block-level content. In other words, the text is rendered as
paragraphs, headers, lists, blockquotes, etc. Any inline syntax within those elements is processed as well.
-For example, the following:
+For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
# A header.
@@ -105,19 +98,6 @@ A *Markdown* paragraph.
```
-... is rendered as:
-
-``` html
-
-A header.
-A Markdown paragraph.
-
-- A list item.
-- A second list item.
-
-
-```
-
!!! warning
Forcing elements to be parsed as `block` elements when they are not by default could result in invalid HTML.
@@ -133,22 +113,17 @@ of the element so long as it is one of the `block` or `span` tags.
The content of a `span` element is not parsed into block-level content. In other words, the content will not be
rendered as paragraphs, headers, etc. Only inline syntax will be rendered, such as links, strong, emphasis, etc.
-For example, the following:
+For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
# *Not* a header
```
-... is rendered as:
-
-``` html
-
-# Not a header
-
-```
-
### Ignored Elements
The following tags are always ignored, regardless of any `markdown` attribute: `canvas`, `math`, `option`, `pre`,
@@ -161,9 +136,12 @@ When nesting multiple levels of raw HTML elements, a `markdown` attribute must b
element. For any block-level element which does not have a `markdown` attribute, everything inside that element is
ignored, including child elements with `markdown` attributes.
-For example, the following:
+For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
# Article Title
@@ -186,23 +164,6 @@ A Markdown paragraph.
```
-... is rendered as:
-
-```html
-
-Article Title
-A Markdown paragraph.
-
-Section 1 Title
-Custom raw **HTML** which gets ignored.
-
-
-Section 2 Title
-Markdown content.
-
-
-```
-
When the value of an element's `markdown` attribute is more permissive that its parent, then the parent's stricter
behavior is enforced. For example, a `block` element nested within a `span` element will be parsed using the `span`
behavior. However, if the value of an element's `markdown` attribute is the same as, or more restrictive than, its
@@ -211,26 +172,18 @@ elements or `span` elements as children and each element will be parsed using th
### Tag Normalization
-While the default behavior is for Markdown to not alter raw HTML, as this extension is parsing the content of raw HTML elements, it will do some normalization of the tags of block-level elements. For example, the following raw HTML:
+While the default behavior is for Markdown to not alter raw HTML, as this extension is parsing the content of raw HTML elements, it will do some normalization of the tags of block-level elements. For example:
-```
+``` md-render
+---
+extensions: [md_in_html]
+---
A Markdown paragraph with *no* closing tag.
A raw paragraph with *no* closing tag.
```
-... is rendered as:
-
-``` html
-
-A Markdown paragraph with no closing tag.
-
-A raw paragraph with *no* closing tag.
-
-
-```
-
Notice that the parser properly recognizes that an unclosed `` tag ends when another `
` tag begins or when the
parent element ends. In both cases, a closing `
` was added to the end of the element, regardless of whether a
`markdown` attribute was assigned to the element.
diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md
index 7bb90870..4a5a9b10 100644
--- a/docs/extensions/nl2br.md
+++ b/docs/extensions/nl2br.md
@@ -29,16 +29,12 @@ hard breaks; like StackOverflow and [GitHub][] flavored Markdown do.
Example
-------
-```pycon
->>> import markdown
->>> text = """
-... Line 1
-... Line 2
-... """
->>> html = markdown.markdown(text, extensions=['nl2br'])
->>> print html
-Line 1
-Line 2
+``` md-render
+---
+extensions: [nl2br]
+---
+Line 1
+Line 2
```
Usage
diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md
index f2c6946a..733e7cff 100644
--- a/docs/extensions/sane_lists.md
+++ b/docs/extensions/sane_lists.md
@@ -33,7 +33,10 @@ Sane Lists do not allow the mixing of list types. In other words, an ordered
list will not continue when an unordered list item is encountered and
vice versa. For example:
-```md
+``` md-render
+---
+extensions: [sane_lists]
+---
1. Ordered item 1
2. Ordered item 2
@@ -41,27 +44,16 @@ vice versa. For example:
* Unordered item 2
```
-will result in the following output:
-
-```html
-
- - Ordered item 1
- - Ordered item 2
-
-
-
- - Unordered item 1
- - Unordered item 2
-
-```
-
Whereas the default Markdown behavior would be to generate an unordered list.
Note that, unlike the default Markdown behavior, if a blank line is not
included between list items, the different list type is ignored completely.
This corresponds to the behavior of paragraphs. For example:
-```md
+```md-render
+---
+extensions: [sane_lists]
+---
A Paragraph.
* Not a list item.
@@ -69,22 +61,13 @@ A Paragraph.
* Not a separate list item.
```
-With this extension the above will result in the following output:
-
-```html
-A Paragraph.
-* Not a list item.
-
-
- - Ordered list item.
- * Not a separate list item.
-
-```
-
Sane lists also recognize the number used in ordered lists. Given the following
list:
-```md
+```md-render
+---
+extensions: [sane_lists]
+---
4. Apples
5. Oranges
6. Pears
@@ -92,15 +75,6 @@ list:
By default markdown will ignore the fact that the first line started
with item number "4" and the HTML list will start with a number "1".
-This extension will result in the following HTML output:
-
-```html
-
- - Apples
- - Oranges
- - Pears
-
-```
In all other ways, Sane Lists should behave as normal Markdown lists.
diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md
index 607340b2..2ed2f7dd 100644
--- a/docs/extensions/tables.md
+++ b/docs/extensions/tables.md
@@ -1,4 +1,4 @@
----
+--
title: Tables Extension
---
@@ -32,38 +32,18 @@ Tables are defined using the syntax established in [PHP Markdown Extra][php].
[php]: http://www.michelf.com/projects/php-markdown/extra/#table
-Thus, the following text (taken from the above referenced PHP documentation):
+Consider the following text (taken from the above referenced PHP documentation).
-```md
+``` md-render
+---
+extensions: [tables]
+---
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
```
-will be rendered as:
-
-```html
-
-
-
- First Header
- Second Header
-
-
-
-
- Content Cell
- Content Cell
-
-
- Content Cell
- Content Cell
-
-
-
-```
-
!!! seealso "See Also"
The [Attribute Lists](./attr_list.md) extension includes support for defining attributes on table cells.
diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
index b7061204..f9d58006 100644
--- a/docs/extensions/toc.md
+++ b/docs/extensions/toc.md
@@ -33,25 +33,23 @@ By default, all headers will automatically have unique `id` attributes
generated based upon the text of the header. Note this example, in which all
three headers would have the same `id`:
-```md
+``` md-render
+---
+extensions: [toc]
+---
#Header
#Header
#Header
```
-Results in:
-
-```html
-Header
-Header
-Header
-```
-
Place a marker in the document where you would like the Table of Contents to
appear. Then, a nested list of all the headers in the document will replace the
-marker. The marker defaults to `[TOC]` so the following document:
+marker. The marker defaults to `[TOC]`.
-```md
+``` md-render
+---
+extensions: [toc]
+---
[TOC]
# Header 1
@@ -59,23 +57,6 @@ marker. The marker defaults to `[TOC]` so the following document:
## Header 2
```
-would generate the following output:
-
-```html
-
-Header 1
-Header 2
-```
-
Regardless of whether a `marker` is found in the document (or disabled), the
Table of Contents is available as an attribute (`toc`) on the Markdown class.
This allows one to insert the Table of Contents elsewhere in their page
@@ -122,33 +103,20 @@ the header. However, occasionally that is not desirable. In that case, if this
extension is used in conjunction with the [Attribute Lists Extension] and a
`data-toc-label` attribute is defined on the header, then the contents of that
attribute will be used as the text label for the item in the Table of Contents.
-For example, the following Markdown:
+For example:
[Attribute Lists Extension]: attr_list.md
-```md
+``` md-render
+---
+extensions: [toc, attr_list]
+---
[TOC]
# Functions
## `markdown.markdown(text [, **kwargs])` { #markdown data-toc-label='markdown.markdown' }
```
-would generate the following output:
-
-```html
-
-
- -
- Functions
-
-
-
-
-Functions
-markdown.markdown(text [, **kwargs])
-```
Notice that the text in the Table of Contents is much cleaner and easier to read
in the context of a Table of Contents. The `data-toc-label` is not included in
@@ -224,15 +192,16 @@ The following options are provided to configure the output:
suppose the Markdown text for a page should not contain any headers higher
than level 3 (``). The following will accomplish that:
- :::pycon
- >>> text = '''
- ... #Some Header
- ... ## Next Level'''
- >>> from markdown.extensions.toc import TocExtension
- >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
- >>> print html
- Some Header
- Next Level
'
+ ``` pycon
+ >>> text = '''
+ ... #Some Header
+ ... ## Next Level'''
+ >>> from markdown.extensions.toc import TocExtension
+ >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
+ >>> print html
+ Some Header
+ Next Level
'
+ ```
* **`slugify`**:
Callable to generate anchors.
diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md
index 8750f284..b0f25383 100644
--- a/docs/extensions/wikilinks.md
+++ b/docs/extensions/wikilinks.md
@@ -29,18 +29,15 @@ This extension is included in the standard Markdown library.
## Syntax
A ``[[bracketed]]`` word is any combination of upper or lower case letters,
-number, dashes, underscores and spaces surrounded by double brackets. Therefore
+number, dashes, underscores and spaces surrounded by double brackets.
-```md
+``` md-render
+---
+extensions: [wikilinks]
+---
[[Bracketed]]
```
-would produce the following HTML:
-
-```html
-Bracketed
-```
-
Note that WikiLinks are automatically assigned `class="wikilink"` making it
easy to style WikiLinks differently from other links on a page if one so
desires. See below for ways to alter the class.
@@ -49,16 +46,13 @@ Also note that when a space is used, the space is converted to an underscore in
the link but left as-is in the label. Perhaps an example would illustrate this
best:
-```md
+``` md-render
+---
+extensions: [wikilinks]
+---
[[Wiki Link]]
```
-becomes
-
-```html
-Wiki Link
-```
-
## Usage
See [Extensions](index.md) for general extension usage. Use `wikilinks` as the
@@ -105,10 +99,17 @@ For an example, let us suppose links should always point to the sub-directory
... )
```
-The above would result in the following link for `[[WikiLink]]`.
+The above configuration would result in the following:
-```html
-WikiLink
+``` md-render
+---
+extensions: [wikilinks]
+extension_configs:
+ wikilinks:
+ base_url: /wiki/
+ end_url: .html
+---
+[[WikiLink]]
```
If you want to do more that just alter the base and/or end of the URL, you
@@ -135,8 +136,14 @@ The option is also provided to change or remove the class attribute.
Would cause all WikiLinks to be assigned to the class `myclass`.
-```html
-WikiLink
+``` md-render
+---
+extensions: [wikilinks]
+extension_configs:
+ wikilinks:
+ html_class: myclass
+---
+[[WikiLink]]
```
## Using with Meta-Data extension
@@ -152,18 +159,15 @@ meta-data keywords are:
When used, the meta-data will override the settings provided through the
`extension_configs` interface.
-This document:
+For example (notice the blank `wiki_html_class`):
-```md
+``` md-render
+---
+extensions: [wikilinks, meta]
+---
wiki_base_url: http://example.com/
wiki_end_url: .html
wiki_html_class:
A [[WikiLink]] in the first paragraph.
```
-
-would result in the following output (notice the blank `wiki_html_class`):
-
-```html
-
A WikiLink in the first paragraph.
-```
diff --git a/mkdocs.yml b/mkdocs.yml
index 32950f3e..7c8fe760 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,7 +7,7 @@ site_author: "The Python-Markdown Project"
copyright: "Copyright © 2010-2026 The Python-Markdown Project."
use_directory_urls: true
-watch: [markdown, .zensical/scripts, .zensical/mkdocstring_templates]
+watch: [markdown, .zensical/scripts, .zensical/mkdocstring_templates, tools]
theme:
variant: modern
@@ -160,6 +160,9 @@ markdown_extensions:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
+ - name: md-render
+ class: md-render
+ format: !!python/name:tools.superfences_formaters.md_render
plugins:
diff --git a/pyproject.toml b/pyproject.toml
index abbdebe0..1cc76c1b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,7 +55,7 @@ docs = [
'mkdocstrings==1.0.6',
'mkdocstrings-python==1.16.8',
'pygments==2.21.0',
- 'pymdown-extensions==11.0.2'
+ 'pymdown-extensions==11.0.2',
]
[project.urls]
diff --git a/tools/__init__.py b/tools/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tools/superfences_formaters.py b/tools/superfences_formaters.py
new file mode 100644
index 00000000..24518c8b
--- /dev/null
+++ b/tools/superfences_formaters.py
@@ -0,0 +1,85 @@
+"""Generate Markdown isolated from our current document options."""
+
+# Code copied from
+# https://github.com/facelessuser/pymdown-extensions/blob/0701c57263b154d60eabf7c64091169619255403/tools/pymdownx_md_render.py
+# with modifications.
+
+import markdown
+import yaml
+import re
+from collections import OrderedDict
+
+
+def yaml_load(stream, loader=yaml.Loader):
+ """
+ Custom YAML loader.
+
+ Load all strings as Unicode.
+ http://stackoverflow.com/a/2967461/3609487
+ """
+
+ def construct_yaml_str(self, node):
+ """Override the default string handling function to always return Unicode objects."""
+
+ return self.construct_scalar(node)
+
+ class Loader(loader):
+ """Custom Loader."""
+
+ Loader.add_constructor(
+ 'tag:yaml.org,2002:str',
+ construct_yaml_str
+ )
+
+ return yaml.load(stream, Loader)
+
+
+def get_frontmatter(text):
+ """Get front matter from string."""
+
+ frontmatter = OrderedDict()
+
+ if text.startswith("---"):
+ m = re.search(r'^(-{3}\r?\n(?!\r?\n)(.*?)(?<=\n)(?:-{3}|\.{3})\r?\n)', text, re.DOTALL)
+ if m:
+ yaml_okay = True
+ try:
+ frontmatter = yaml_load(m.group(2))
+ if frontmatter is None:
+ frontmatter = OrderedDict()
+ # If we didn't get a dictionary, we don't want this as it isn't front matter.
+ assert isinstance(frontmatter, (dict, OrderedDict)), TypeError
+ except Exception:
+ # We had a parsing error. This is not the YAML we are looking for.
+ yaml_okay = False
+ frontmatter = OrderedDict()
+
+ if yaml_okay:
+ text = text[m.end(1):]
+
+ return frontmatter, text
+
+
+def md_render(src="", language="", class_name=None, options=None, md="", **kwargs):
+ """ Render Markdown in code block and rendered output in result code block. """
+ try:
+ fm, text = get_frontmatter(src)
+ html = markdown.markdown(
+ text,
+ extensions=fm.get('extensions', []),
+ extension_configs=fm.get('extension_configs', {})
+ )
+ except Exception:
+ import traceback
+ print(traceback.format_exc())
+ raise
+
+ options = options or {}
+ if 'title' not in options:
+ options['title'] = 'Markdown Source'
+ result_options = options.copy()
+ result_options['title'] = 'HTML Output'
+
+ source = md.preprocessors['fenced_code_block'].highlight(text, 'markdown', options, md, **kwargs)
+ output = md.preprocessors['fenced_code_block'].highlight(html, 'html', result_options, md, **kwargs)
+ return f'{source}\n{output}'