9.10 New Experimental Feature
Blocks is currently a new, experimental extension type available in Pymdown Extensions that allows for writing a new kind of block extension in Python Markdown. With this new addition, we've added a number of new extensions utilizing this new extension type. While its intention is to hopefully replace extensions like Details and Tabbed, there are currently no immediate plans to deprecate those plugins.
Any and all feedback regarding these new, experimental blocks is appreciated. Please provide feedback here: #1973.
The HTML block allows a user to wrap Markdown in arbitrary HTML elements.
By default, the meta-plugin is registered when
pymdownx.blocks is registered, but if you were customizing which meta-plugins get loaded, you can do so by doing the following:
import markdown from pymdownx.blocks.html import HTML md = markdown.Markdown(extensions=['pymdownx.blocks.html'])
Generally, HTML blocks can be defined simply by specifying the
html generic block type followed by the tag name.
/// html | div some *markdown* content ///
some markdown content
Classes and IDs and arbitrary attributes can be specified by using selector-like notation:
div.my-classwill add a class of name
my-classto a tag of name
div#some-idwill add an ID of name
some-idto a tag of name
div[attr]will add an attribute of name
attrto a tag of name
div. You can also add values (
div[attr=value]), quoted values (
div[attr="quoted value"]), and even multiple values (
div[attr1=value attr2="quoted value"]).
- Attributes can also be chained:
/// html | div[style='border: 1px solid red;'] some *markdown* content ///
By default HTML blocks will automatically have the content rendering determined from tag name, so
div blocks will be treated as block elements,
span will be treated as inline elements, and things like
pre will treat the content as raw text that needs HTML escaping, and things like
script will be treated as raw content does not need HTML escaping. With that said, there may be cases where an HTML element isn't properly recognized yet, or the user simply wants to control how the element processes its content, in these cases, the
markdown option can be used to specify how Markdown content is handled.
| ||Parsed block content will be handled by the Markdown parser as content under a block element.|
| ||Parsed block content will be handled by the Markdown parser as content under an inline element.|
| ||Parsed block content will be preserved. No additional Markdown parsing will be applied. Content will be HTML escaped to preserve the content as is.|
| ||Depending on whether the wrapping parent is a block element, inline element, or something like a code element, Blocks will choose the best approach for the content. Decision is made based on the element returned by the |
| ||Like |
Raw and HTML Mode
When using raw tags or forcing raw mode with
markdown: raw (HTML escaped) or
markdown: html (no HTML escaping), code must be indented. This is because Python Markdown will look for and process raw HTML in non indented blocks. The only avoid this is to use indented code blocks. If content is not indented, the content may be missing at the end.
Recognized raw block tags:
Recognized raw HTML tags:
Also, make sure to have a new line before indented content so it is not recognized as an attempt to specify YAML options.
In the following example we force
pre to handle content as Markdown block content instead of the usual raw content default.
/// html | pre some *markdown* content /// /// html | pre markdown: block some *markdown* content ///
some *markdown* content
some markdown content
| ||string||String value to control how Markdown content is processed. Valid options are: |
| ||string||A string that defines attributes for the outer, wrapper element.|