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.