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.

-
-``` +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 -
-

Don't try this at home

-

...

-
-``` - -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 -
-

This is an admonition box without a title.

-
-``` - 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 - -``` - rST suggests the following "types": `attention`, `caution`, `danger`, `error`, `hint`, `important`, `note`, `tip`, and `warning`; however, you're free to use whatever you want. diff --git a/docs/extensions/attr_list.md b/docs/extensions/attr_list.md index 1050676f..068c2f0f 100644 --- a/docs/extensions/attr_list.md +++ b/docs/extensions/attr_list.md @@ -34,8 +34,8 @@ The basic syntax was inspired by Maruku's Attribute Lists feature (see [web arch An example attribute list might look like this: -```text -{: #someid .someclass somekey='some value' } +``` markdown +{ #someid .someclass somekey='some value' } ``` A word which starts with a hash (`#`) will set the id of an element. @@ -48,13 +48,13 @@ A key/value pair (`somekey='some value'`) will assign that pair to the element. Be aware that while the dot syntax will add to a class, using key/value pairs will always override the previously defined attribute. Consider the following: -```text -{: #id1 .class1 id=id2 class="class2 class3" .class4 } +``` markdown +{ #id1 .class1 id=id2 class="class2 class3" .class4 } ``` The above example would result in the following attributes being defined: -```text +``` markdown id="id2" class="class2 class3 class4" ``` @@ -64,18 +64,18 @@ list `{: checked }` would result in `checked` if the [output format](../library. Curly braces can be backslash escaped to avoid being identified as an attribute list. -```text +``` markdown \{ not an attribute list } ``` Opening and closing curly braces which are empty or only contain whitespace are ignored whether they are escaped or not. Additionally, any attribute lists which are not located in the specific locations documented below are ignored. -The colon after the opening brace is optional, but is supported to maintain consistency with other implementations. +A colon after the opening brace is optional, but is supported to maintain consistency with other implementations. Therefore, the following is also a valid attribute list: -```text -{ #someid .someclass somekey='some value' } +``` markdown +{: #someid .someclass somekey='some value' } ``` In addition, the spaces after the opening brace and before the closing brace are optional. They are recommended as @@ -91,31 +91,24 @@ characters are reduced to a single underscore. To define attributes for a block level element, the attribute list should be defined on the last line of the block by itself. -```text +``` md-render +--- +extensions: [attr_list] +--- This is a paragraph. -{: #an_id .a_class } -``` - -The above results in the following output: - -```html -

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 -

A setext style header

-

A hash style header

+### A hash style header ### { #hash } ``` !!! seealso "See Also" @@ -128,14 +121,11 @@ The above results in the following output: To define attributes on inline elements, the attribute list should be defined immediately after the inline element with no white space. -```text -[link](http://example.com){: class="foo bar" title="Some title!" } -``` - -The above results in the following output: - -```html -

link

+``` md-render +--- +extensions: [attr_list] +--- +[link](http://example.com){ class="foo bar" title="Some title!" } ``` If the [tables](./tables.md) extension is enabled, attribute lists can be defined on table cells. To differentiate @@ -143,31 +133,15 @@ attributes for an inline element from attributes for the containing cell, the at the content by at least one space and be defined at the end of the cell content. As table cells can only ever be on a single line, the attribute list must remain on the same line as the content of the cell. -```text +``` md-render +--- +extensions: [tables, attr_list] +--- | set on td | set on em | |--------------|-------------| | *a* { .foo } | *b*{ .foo } | ``` -The above example results in the following output: - -```html - - - - - - - - - - - - - -
set on tdset on em
ab
-``` - Note that in the first column, the attribute list is preceded by a space; therefore, it is assigned to the table cell (`` element). However, in the second column, the attribute list is not preceded by a space; therefore, it is assigned to the inline element (``) which immediately preceded it. diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md index 7ef734a3..6967ff08 100644 --- a/docs/extensions/code_hilite.md +++ b/docs/extensions/code_hilite.md @@ -86,10 +86,11 @@ block will not be highlighted. ## Syntax -The CodeHilite extension follows the same [syntax][] as regular Markdown code -blocks, with one exception. The highlighter needs to know what language to use for -the code block. There are three ways to tell the highlighter what language the -code block contains and each one has a different result. +The CodeHilite extension follows the same [syntax][] as regular (indented) +Markdown code blocks, with one exception. The highlighter needs to know what +language to use for the code block. There are three ways to tell the +highlighter what language the code block contains and each one has a +different result. !!! tip The format of the language identifier only effects the display of line numbers @@ -105,71 +106,56 @@ code block contains and each one has a different result. If the first line of the code block contains a shebang, the language is derived from that and line numbers are used. -```md +``` md-render +--- +extensions: [codehilite] +--- #!/usr/bin/python # Code goes here ... ``` -Will result in: - -``` python -#!/usr/bin/python -# Code goes here ... -``` - ### Shebang (no path) If the first line contains a shebang, but the shebang line does not contain a path (a single `/` or even a space), then that line is removed from the code block before processing. Line numbers are used. -```md +``` md-render +--- +extensions: [codehilite] +--- #!python # Code goes here ... ``` -Will result in: - -``` python -# Code goes here ... -``` - ### Colons If the first line begins with three or more colons, the text following the colons identifies the language. The first line is removed from the code block before processing and line numbers are not used. -```md +``` md-render +--- +extensions: [codehilite] +--- :::python # Code goes here ... ``` -Will result in: - -``` python -# Code goes here ... -``` - Certain lines can be selected for emphasis with the colon syntax. When using Pygments' default CSS styles, emphasized lines have a yellow background. This is useful to direct the reader's attention to specific lines. -```md +``` md-render +--- +extensions: [codehilite] +--- :::python hl_lines="1 3" # This line is emphasized # This line isn't # This line is emphasized ``` -Will result in: - -``` python hl_lines="1 3" - # This line is emphasized - # This line isn't - # This line is emphasized -``` - !!! tip `hl_lines` is named for Pygments' option meaning "highlighted lines". @@ -179,19 +165,11 @@ CodeHilite is completely backwards compatible so that if a code block is encountered that does not define a language, the block is simply wrapped in `
` 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 -
-
Apple
-
Pomaceous fruit of plants of the genus Malus in -the family Rosaceae.
- -
Orange
-
The fruit of an evergreen tree of the genus Citrus.
-
-``` - Usage ----- diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md index 464ab232..1277fa8a 100644 --- a/docs/extensions/fenced_code_blocks.md +++ b/docs/extensions/fenced_code_blocks.md @@ -35,7 +35,10 @@ Fenced code blocks begin with three or more backticks (` ``` `) or tildes (`~~~` a matching set of backticks or tildes on a line by themselves. The closing set must contain the same number and type of characters as the opening set. It is recommended that a blank line be placed before and after the code block. -````md +```` md-render +--- +extensions: [fenced_code] +--- A paragraph before the code block. ``` @@ -47,7 +50,10 @@ A paragraph after the code block. While backticks seem to be more popular among users, tildes may be used as well. -````md +```` md-render +--- +extensions: [fenced_code] +--- ~~~ a one-line code block ~~~ @@ -56,7 +62,10 @@ a one-line code block To include a set of backticks (or tildes) within a code block, use a different number of backticks for the delimiters. -`````md +````` md-render +--- +extensions: [fenced_code] +--- ```` ``` ```` @@ -65,7 +74,10 @@ delimiters. Fenced code blocks can have a blank line as the first and/or last line of the code block and those lines will be preserved. -````md +```` md-render +--- +extensions: [fenced_code] +--- ``` a three-line code block @@ -76,7 +88,10 @@ a three-line code block Unlike indented code blocks, a fenced code block can immediately follow a list item without becoming part of the list. -````md +```` md-render +--- +extensions: [fenced_code] +--- * A list item. ``` @@ -97,7 +112,7 @@ deliminator. The attributes should be wrapped in curly braces `{}` and be on the generally best to separate the attribute list from the deliminator with a space. Attributes within the list must be separated by a space. -````md +```` markdown ``` { attributes go here } a code block with attributes ``` @@ -110,7 +125,10 @@ How those attributes will affect the output will depend on various factors as de The language of the code within a code block can be specified for use by syntax highlighters, etc. The language should be prefixed with a dot and not contain any whitespace (`.language-name`). -````md +```` md-render +--- +extensions: [fenced_code] +--- ``` { .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] +--- ``` html

HTML 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] +--- ![Alt text{@id=baz}](path/to/image.jpg) ``` -```html -

Alt text

-``` - ## 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 -
    -
  1. Ordered item 1
  2. -
  3. Ordered item 2
  4. -
- -
    -
  • 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.

- -
    -
  1. Ordered list item. - * Not a separate list item.
  2. -
-``` - 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 -
    -
  1. Apples
  2. -
  3. Oranges
  4. -
  5. Pears
  6. -
-``` 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 HeaderSecond Header
Content CellContent Cell
Content CellContent 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

-

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