Extensions
Python Markdown Extensions Rundown»
- Python Markdown Extensions Rundown
- Installation
- Usage
- tables
- abbr
- attr_list
- markdown_attr_plus
- admonition
- codehilite
- def_list
- footnotes
- meta
- nl2br
- smarty
- toc
- pymdownx.betterem
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.superfences
- pyembed.markdown
- markdown_include.include
- sections
- outline
- cite
- collapse
- custom_span_class
- figcap
- fontawesome-markdown
- steroids.wikilink
- steroids.kbd
- steroids.replimgsrc
- steroids.absimgsrc
- Other extensions of interest:
- Varia
- Deprecated
Installation»
This is a collected list of packages to install:
pip install --user --upgrade PyYAML
pip install --user --upgrade Markdown
pip install --user --upgrade pymdown-extensions
pip install --user --upgrade python-markdown-pretty
pip install --user --upgrade pyembed-markdown
pip install --user --upgrade markdown-include
pip install --user --upgrade mdx_sections
pip install --user --upgrade git+https://github.com/twardoch/markdown-steroids.git/@master#egg=mdx_steroids-0.4.0
Usage»
Python»
md = markdown.Markdown( extensions=[ 'markdown_include.include', 'markdown_include.include', 'path/to/my_ext.py', ], extension_configs={ 'markdown_include.include': { base_path: './srcdocs' } } ) html = md.convert(markdown_string)
Command-line»
- Create a
config.ymlfile that describes theextension_configsdictionary using YAML:
markdown_include.include: base_path: './srcdocs'
- Run:
$ python -m markdown \ -x path/to/my_ext.py \ -x markdown_include.include \ -c config.yml \ -o 'html5' -f output.html input.md
tables»
The tables extension adds the ability to create tables in Markdown documents.
Installation»
preinstalled
Example»
| First Header | Second Header |
|---|---|
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Input Markdown»
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
Output HTML»
<table> <thead> <tr> <th>First Header</th> <th>Second Header</th> </tr> </thead> <tbody> <tr> <td>Content Cell</td> <td>Content Cell</td> </tr> <tr> <td>Content Cell</td> <td>Content Cell</td> </tr> </tbody> </table>
abbr»
The abbr extension adds the ability to define abbreviations, which are then wrapped in an <abbr> tag.
Installation»
preinstalled
Example»
The WOFF specification is maintained by the W3C.
Input Markdown»
The WOFF specification is maintained by the W3C. *[WOFF]: Web Open Font Format *[W3C]: World Wide Web Consortium
Output 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>
attr_list»
The attr_list extension adds a syntax to define attributes on the various HTML elements in markdown’s output.
Installation»
preinstalled
Example»
Header 3»
This is a paragraph.
Input Markdown»
### Header 3 {: #header_3 } [link](http://example.com){: class="foo bar" title="Some title!" } This is a paragraph. {: #an_id .class_1 .class_2 title="explain" }
Output HTML»
<h3 id="header_3">Header 3</h3> <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p> <p id="an_id" class="class_1 class_2" title="explain">This is a paragraph.</p>
markdown_attr_plus»
The markdown_attr_plus extension modifies the default Attribute List extension to include {^ ... }, {o ... }, and {> ... } syntax, which specifically only modify lists, list items, and blockquotes respectively.
Installation»
pip install --user --upgrade markdown-attr-plus
Docs»
admonition»
The admonition extension adds rST-style admonitions to Markdown documents.
Installation»
preinstalled
Docs»
Common admonition types are: attention, caution, danger, error, hint, important, note, tip, warning
codehilite»
The codehilite extension adds code/syntax highlighting to standard Python-Markdown code blocks using Pygments.
Installation»
preinstalled
Options»
codehilite: css_class : 'code' linenums : null guess_lang : true use_pygments : true pygments_style : 'default'
def_list»
The def_list extension adds the ability to create definition lists in Markdown documents.
Installation»
preinstalled
Example»
- Apple
- Pomaceous fruit of plants of the genus Malus in
the family Rosaceae. - Orange
- The fruit of an evergreen tree of the genus Citrus.
Input Markdown»
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.
Output HTML»
<dl> <dt>Apple</dt> <dd>Pomaceous fruit of plants of the genus Malus in the family Rosaceae.</dd> <dt>Orange</dt> <dd>The fruit of an evergreen tree of the genus Citrus.</dd> </dl>
footnotes»
The footnotes extension adds syntax for defining footnotes in Markdown documents.
Installation»
preinstalled
Options»
footnotes: PLACE_MARKER : '///Footnotes Go Here///' # if the place marker text is not found in the document, # the footnote definitions are placed at the end of the resulting HTML document UNIQUE_IDS : false BACKLINK_TEXT : '↩'
Example»
Footnotes1 have a label2 and the footnote’s content.
Input Markdown»
Footnotes[^1] have a label[^@#$%] and the footnote's content. [^1]: This is a footnote content. [^@#$%]: A footnote on the label: "@#$%". ///Footnotes Go Here///
Output HTML»
<p>Footnotes<a href="#fn:1" id="fnref:1" title="see footnote" class="footnote">[1]</a> have a label<a href="#fn:2" id="fnref:2" title="see footnote" class="footnote">[2]</a> and the footnote’s content.</p> <div class="footnotes"> <hr> <ol> <li id="fn:1"> <p>This is a footnote content. <a href="#fnref:1" title="return to article" class="reversefootnote"> ↩</a></p> </li> <li id="fn:2"> <p>A footnote on the label: “@#$%”. <a href="#fnref:2" title="return to article" class="reversefootnote"> ↩</a></p> </li> </ol> </div>
meta»
The meta extension adds a syntax for defining meta-data about a document.
Installation»
preinstalled
nl2br»
The nl2br extension will cause newlines to be treated as hard breaks.
Installation»
preinstalled
smarty»
The smarty extension converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.
Installation»
preinstalled
Options»
smarty: smart_dashes : true # convert dashes smart_quotes : true # convert straight quotes smart_angled_quotes : false # whether to convert angled quotes smart_ellipses : true # whether to convert ellipses substitutions: # overwrite default substitutions left-single-quote : '‘' # ' right-single-quote : '’' # ' left-double-quote : '“' # " right-double-quote : '”' # " left-angle-quote : '«' # << right-angle-quote : '»' # >> ellipsis : '…' # ... ndash : '–' # -- mdash : '—' # ---
toc»
The toc extension
Installation»
preinstalled
Options»
toc: permalink : '❡' marker : '[TOC]' title : 'Table of Contents' anchorlink : true baselevel : 1 separator : '-' slugify : headerid.slugify
pymdownx.betterem»
The pymdownx.betterem extension improves emphasis (bold and italic) handling.
Installation»
pip install --user --upgrade pymdown-extensions
Docs»
Options»
pymdownx.betterem: smart_enable : 'all' # 'all' | 'asterisk' | 'underscore' | 'none'
pymdownx.magiclink»
The pymdownx.magiclink extension
Installation»
pip install --user --upgrade pymdown-extensions
Options»
pymdownx.magiclink: hide_protocol : true
Example»
Visit github.com/twardoch for more info.
Input Markdown»
Visit https://github.com/twardoch for more info.
Output HTML»
<p>Visit <a href="https://github.com/twardoch">https://github.com/twardoch</a> for more info.</p>
pymdownx.mark»
The pymdownx.mark extension
Installation»
pip install --user --upgrade pymdown-extensions
Options»
pymdownx.mark: smart_mark : true # Allows for ==mark==me==
pymdownx.superfences»
The pymdownx.superfences extension adds flexible ways to define code blocks, and replaces the fenced_code extension.
Installation»
pip install --user --upgrade pymdown-extensions
Options»
pymdownx.superfences: disable_indented_code_blocks : false nested : true uml_flow : false uml_sequence : false
Example»
```python
class MyClass(object):
def init(self):
return passprint(“Done”)
```
Input Markdown»
> ```python class MyClass(object): def __init__(self): return pass > print("Done") ```
Output HTML»
<blockquote> <pre class=" language-python"><code class=" language-python"><span class="token keyword">class</span> <span class="token class-name">MyClass</span><span class="token punctuation">(</span>object<span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token keyword">def</span> <span class="token function">__init__</span><span class="token punctuation">(</span>self<span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token keyword">return</span> <span class="token keyword">pass</span> <span class="token keyword">print</span><span class="token punctuation">(</span><span class="token string">"Done"</span><span class="token punctuation">)</span> </code></pre> </blockquote>
pyembed.markdown»
The pyembed.markdown extension allows you to embed content in your Markdown websites and documents from a wide range of producers using OEmbed.
Installation»
pip install --user --upgrade pyembed-markdown
Docs»
markdown_include.include»
The markdown_include.include extension replaces the Welcome to the markdown-rundown wiki! statement with the contents of Home.md. It works recursively, prior to any other Markdown processing.
Installation»
pip install --user --upgrade markdown-include
Options»
markdown_include.include: base_path : './srcdocs/' encoding : 'utf-8'
sections»
The sections extension adds a small amount of structure to Markdown documents.
Installation»
pip install --user --upgrade mdx_sections
outline»
The outline extension uses the h1-h6 headings to create HTML section elements with the sectionN class, where N is the header level being wrapped. Also, the header attributes get moved to the wrapper.
Installation»
pip install --user --upgrade mdx_outline
cite»
The cite extension wraps the inline content surrounded by three double quotes into cite tags.
Installation»
pip install --user --upgrade mdx_cite
collapse»
The collapse extension defines collapsible areas.
The collapse extension makes problems
Installation»
pip install --user --upgrade mdx_collapse
Example»
<<< “Collapsible stuff”
* Stuff 1
* Stuff 2
* Stuff 3
* Stuff 4
Input Markdown»
<<< "Collapsible stuff" * Stuff 1 * Stuff 2 * Stuff 3 * Stuff 4
Output HTML»
<div class="panel panel-default panel-collapsible"> <div class="panel-heading"> <a data-toggle="collapse" data-target="#collapse1" /> </div> <div id="collapse1" class="panel-body collapse in"> <ul> <li>Stuff 1</li> <li>Stuff 2</li> <li>Stuff 3</li> <li>Stuff 4</li> </ul> </div> </div>
custom_span_class»
The custom_span_class allows adding span elements with custom class.
Installation»
pip install --user --upgrade mdx_customspanclass
figcap»
The figcap extension converts a Markdown image into a HTML <figure> element.
Installation»
pip install --user --upgrade git+https://github.com/mkszk/mdx_figcap.git
Example»
Input Markdown»
Output HTML»
<figure><img alt="This is an alt text" src="../test.jpg" title="This is a **caption** with Markdown"> <figcaption>This is a <strong>caption</strong> with Markdown</figcaption> </figure>
fontawesome-markdown»
The fontawesome-markdown looks for things like ``` and replaces them with the Font Awesome icon markup.
Installation»
pip install --user --upgrade fontawesome-markdown
steroids.wikilink»
The steroids.wikilink extension parses wikilinks in the style of the Gollum wiki and the Github Wiki system. It will convert links such as [[Page name]] to [Page name](/Page-name/). You can specify the start, end and separator strings.
Installation»
pip install --user --upgrade git+https://github.com/twardoch/markdown-steroids.git
Options»
steroids.wikilink: base_url : '/' # String to append to beginning or URL. end_url : '/' # String to append to end of URL. html_class : 'wikilink' # CSS hook. Leave blank for none. space_sep : '-' # String that replaces the space, "-" by default. build_url : build_url # Alternative callable formats URL from label.
steroids.kbd»
The steroids.kbd extension converts syntax for user keyboard entry: ||Cmd+K|| into <kbd>Cmd+K</kbd>.
Installation»
pip install --user --upgrade git+https://github.com/twardoch/markdown-steroids.git
Options»
steroids.kbd: repl_mac : false # Replace macOS symbols html_class : 'kbd' # CSS hook. Leave blank for none
steroids.replimgsrc»
The steroids.replimgsrc extension finds and replaces portions of an image URL.
Installation»
pip install --user --upgrade git+https://github.com/twardoch/markdown-steroids.git
Options»
steroids.replimgsrc: find : 'https://github.com/repo/blob/master/images/' replace : '../img/'
steroids.absimgsrc»
The steroids.absimgsrc replaces relative image URLs with absolute ones.
Installation»
pip install --user --upgrade git+https://github.com/twardoch/markdown-steroids.git
Options»
steroids.absimgsrc: base_url : 'https://github.com/repo/blob/master/images/' # Base URL to which the relative paths will be appended
Other extensions of interest:»
- github.com/Griffon26/mdx_spantables
- github.com/livio/DocDown-Python/
- github.com/Wenzil/mdx_bleach
- github.com/kernc/mdx_unimoji
- github.com/darwindarak/mdx_bib
- github.com/kdeldycke/mdx_titlecase
- github.com/cprieto/mdx_downheader
- github.com/zestedesavoir/Python-ZMarkdown/tree/master-zds/markdown/extensions
- github.com/zestedesavoir/Python-ZMarkdown/blob/master-zds/markdown/extensions/french_typography.py
- github.com/zestedesavoir/Python-ZMarkdown/blob/master-zds/markdown/extensions/grid_tables.py
- github.com/zestedesavoir/Python-ZMarkdown/blob/master-zds/markdown/extensions/header_dec.py
- github.com/zestedesavoir/Python-ZMarkdown/blob/master-zds/markdown/extensions/mathjax.py
- github.com/idaholab/moose/tree/master/python/MooseDocs
- github.com/sander76/svg_animation_plugin/
- github.com/andrewlin12/markdown2png/blob/master/src/md2png/init.py
- github.com/mkdocs/mkdocs/blob/master/mkdocs/relative_path_ext.py
- github.com/cpprefjp/markdown_to_html/blob/master/qualified_fenced_code.py
- github.com/freenode/cms7/blob/master/cms7/mdext.py
- github.com/ckald/pyccoon/blob/master/pyccoon/markdown_extensions.py
Varia»
Deprecated»
pymdownx.headeranchor»
- Use
tocwithpermalinksinstead!
fenced_code»
- Use
pymdownx.superfencesinstead! - Docs: pythonhosted.org/Markdown/extensions/fenced_code_blocks.html
smart_strong»
- Use
pymdownx.bettereminstead! - Docs: pythonhosted.org/Markdown/extensions/smart_strong.html