Built-in markups

These markups are available by default:

Markdown markup

Markdown markup uses Python-Markdown as a backend (version 2.6 or later is required).

There are several ways to enable Python-Markdown extensions.

  • List extensions in a file named markdown-extensions.yaml or markdown-extensions.txt in the configuration directory. The extensions will be automatically applied to all documents.

  • If markdown-extensions.yaml or markdown-extensions.txt is placed into working directory, all documents in that directory will get extensions that are listed in that file.

  • If first line of a document contains “Required extensions: ext1 ext2 ...”, that list will be applied to a document.

  • Finally, one can programmatically pass list of extension names to markups.MarkdownMarkup constructor.

The YAML file should be a list of extensions, possibly with configuration options, for example:

- smarty:
    substitutions:
      left-single-quote: "‚"
      right-single-quote: "‘"
    smart_dashes: False
- toc:
    permalink: True
    separator: "_"
    toc_depth: 3
- sane_lists

Or using a JSON-like syntax:

["smarty", "sane_lists"]

YAML support works only when the PyYAML module is installed.

The txt file is a simple list of extensions, separated by newlines. Lines starting with # are treated as comments and ignored. It is possible to specify string options in brackets, for example:

toc(title=Contents)
sane_lists

The same syntax to specify options works in the Required extensions line. You can put it into a comment to make it invisible in the output:

<!-- Required extensions: toc(title=Contents) sane_lists -->

The Math Markdown extension is enabled by default. This extension supports a syntax for LaTeX-style math formulas (powered by MathJax). The delimiters are:

Inline math

Standalone math

$...$ 1

$$...$$

\(...\)

\[...\]
1

To enable single-dollar-sign delimiter, one should add mdx_math(enable_dollar_delimiter=1) to the extensions list.

The Python-Markdown Extra set of extensions is enabled by default. To disable it, one can enable virtual remove_extra extension (which also completely disables LaTeX formulas support).

The default file extension associated with Markdown markup is .mkd, though many other extensions (including .md and .markdown) are supported as well.

class markups.MarkdownMarkup(filename=None, extensions=None)

Markup class for Markdown language. Inherits AbstractMarkup.

Parameters

extensions (list) – list of extension names

reStructuredText markup

This markup provides support for reStructuredText language (the language this documentation is written in). It uses Docutils Python module.

The file extension associated with reStructuredText markup is .rst.

class markups.ReStructuredTextMarkup(filename=None, settings_overrides=None)

Markup class for reStructuredText language. Inherits AbstractMarkup.

Parameters

settings_overrides (dict) – optional dictionary of overrides for the Docutils settings

Textile markup

This markup provides support for Textile language. It uses python-textile module.

The file extension associated with Textile markup is .textile.

class markups.TextileMarkup(filename=None)

Markup class for Textile language. Inherits AbstractMarkup.