Extensions

Lamarkdown provides access to Python-Markdown’s extension system, to extend the core markdown language. You can determine which extensions to load in several ways:

  • Accept the defaults (which are in place if you don’t have a build file);

  • Write a build file that calls the lamarkdown package, providing one or more extension names (or Extension objects, typically if you want to create your own extensions):

    import lamarkdown as la
    la('attr_list', 'nl2br', 'toc', 'la.cite', 'pymdownx.extra')
    la('la.latex', tex = 'pdflatex')
    
  • Write a build file that calls m.doc(), or another build module that happens to load extension(s); or

  • To avoid extensions altogether, simply write a build file that doesn’t load any extensions. (This would include avoiding calls to m.doc() and other build modules.)

1. Standard Lamarkdown Extensions

Extension Description In m.doc()
la.attr_prefix Permits HTML attributes, including directives, to be specified above a block element (in contrast to attr_list, where they must come below). Notably, this allows attributes/directives to be applied to list elements (whether numbered or bullet-pointed).
la.captions Lets you to assign paragraphs to be captions of tables or images.
la.cite Builds a bibliography based on Bibtex-formatted reference file(s), and in-text citations of the form [@citation_key] (or [@key1 p.15, @key2], etc.).
la.eval Lets you insert placeholders using the syntax $`...`, to be replaced by corresponding values defined in the build file. If allow_code is enabled, this also lets you insert full Python expressions, which will be evaluated and replaced by their result. ✅ (allow_code is False by default)
la.labels Adds numbering schemes to headings, lists, figures and/or tables, and permits cross-referencing.
la.latex Lets you insert LaTeX code, generally for mathematical or diagramming purposes.
la.list_tables Lets you specify the content of a table using nested lists, in order to maintain Markdown readability while permitting arbitrary content within a table.
la.markdown_demo Supports this documentation by formatting sample build files and Markdown input, while also compiling them to produce the corresponding output, shown within an <iframe>.  
la.sections Lets you divide a document into <section> elements using --- dividers, which may be used to create slideshows with RevealJS, for instance.  

2. Standard Python Markdown Extensions

These extensions are bundled with the core Python Markdown engine, on which Lamarkdown is based.

Extension Description In m.doc()?
abbr For abbreviations, using the <abbr> HTML element.
admonition For creating callout/admonition boxes, such as for notes, warnings, etc.
attr_list For adding HTML attributes to various elements (which in turn enables CSS styling).
codehilite Consider pymdownx.superfences + pymdownx.highlight instead.
def_list For creating definition lists, using the <dl>, <dt> and <dd> HTML elements.
extra Shortcut for abbr, attr_list, def_list, fenced_code, footnotes, md_in_html, tables. Consider pymdownx.extra instead.
fenced_code Consider pymdownx.superfences instead.
footnotes For defining labelled footnotes.
legacy_attrs Deprecated.
legacy_em For emphasis syntax that more closely matches the markdown reference implementation.
md_in_html For nesting Markdown syntax inside embedded HTML.
meta For adding key-value metadata to the top of markdown files.
nl2br For treating single newlines in markdown as hard line breaks (rather than whitespace).
sane_lists Slightly nicer handling of markdown lists.
smarty For auto-replacing quotes, ellipses and dashes with proper, non-ASCII symbols.
tables For creating simple tables.
toc Creates a table of contents based on headings in the document.
wikilinks Provides a wiki-style link syntax. This may not work well with Larmarkdown.

3. PyMdown Extensions

These extensions together form a major 3rd-party package. Lamarkdown has a dependency on PyMdown extensions, so they (like those above) are available by default.

Extension Description In m.doc()?
pymdownx.arithmatex Preserves Latex math equations during compilation, so they can be parsed and displayed by Javascript libraries (like MathJax or KaTeX) when the output document is viewed.
pymdownx.b64 Consider using Lamarkdown’s built-in media embedding instead.
pymdownx.betterem Tweaks the handling of emphasis syntax (_ and *).
pymdownx.blocks Supports a secondary extension system
pymdownx.caret For superscript and insertions with the ^ character, using the <sup> and <ins> HTML elements. See also pymdownx.tilde.
pymdownx.critic For marking up insertions and deletions, optionally displayed, using <ins> and <del>.
pymdownx.details For hidable/expandable content using the <details> and <summary> HTML elements.
pymdownx.emoji For inserting emojis by name.
pymdownx.escapeall Tweaks the handling of \ to escape any character.
pymdownx.extra Shortcut for pymdownx.betterem, pymdownx.superfences, abbr, attr_list, def_list, footnotes, md_in_html, tables.
pymdownx.highlight Configures code highlighting for pymdownx.inlinehilite and pymdownx.superfences.
pymdownx.inlinehilite For syntax highlighting of inline code snippets within `...`.
pymdownx.keys For showing keyboard keys, using the <kbd> HTML element.
pymdownx.magiclink For auto-linking URLs in the text without any special syntax (or with various alternative syntaxes).
pymdownx.mark For marking/highlighting text using the <mark> HTML element.
pymdownx.pathconverter Generally unnecessary in Larmarkdown.
pymdownx.progressbar For showing progress bars (though additional CSS is required).
pymdownx.saneheaders Tweaks the handling of # in markdown headers.
pymdownx.smartsymbols For inserting various symbols by ASCII characters: (tm) for ™, --> for →, etc.
pymdownx.snippets For inserting file(s), or parts of a file, into the current markdown document.
pymdownx.striphtml Strips HTML attributes from a document (and also comments, but this is unnecessary in Lamarkdown).
pymdownx.superfences For multi-line code blocks inside ```...```; more flexible version of fenced_code.
pymdownx.tabbed For creating multiple tabs, each showing different content.
pymdownx.tasklist For creating checkboxes for list items.
pymdownx.tilde For subscript and deletions with the ~ character, using the <sub> and <del> HTML elements. See also pymdownx.caret.