‹› markdown

Python-Markdown provides two public functions (markdown.markdown and markdown.markdownFromFile) both of which wrap the public class markdown.Markdown. All submodules support these public functions and class and/or provide extension support.

Modules:

Classes:

  • Markdown –

    A parser which converts Markdown to HTML.

Functions:

  • markdown –

    Convert a markdown string to HTML and return HTML as a Unicode string.

  • markdownFromFile –

    Read Markdown text from a file and write output to a file or a stream.

‹› markdown.Markdown(**kwargs)

A parser which converts Markdown to HTML.

Attributes:

  • Markdown.tab_length (int) –

    The number of spaces which correspond to a single tab. Default: 4.

  • Markdown.ESCAPED_CHARS (list[str]) –

    List of characters which get the backslash escape treatment.

  • Markdown.block_level_elements (list[str]) –

    List of HTML tags which get treated as block-level elements. See markdown.util.BLOCK_LEVEL_ELEMENTS for the full list of elements.

  • Markdown.registeredExtensions (list[Extension]) –

    List of extensions which have called registerExtension during setup.

  • Markdown.doc_tag (str) –

    Element used to wrap document. Default: div.

  • Markdown.stripTopLevelTags (bool) –

    Indicates whether the doc_tag should be removed. Default: ‘True’.

  • Markdown.references (dict[str, tuple[str, str]]) –

    A mapping of link references found in a parsed document where the key is the reference name and the value is a tuple of the URL and title.

  • Markdown.htmlStash (HtmlStash) –

    The instance of the HtmlStash used by an instance of this class.

  • Markdown.output_formats (dict[str, Callable[Element]]) –

    A mapping of known output formats by name and their respective serializers. Each serializer must be a callable which accepts an Element and returns a str.

  • Markdown.output_format (str) –

    The output format set by set_output_format.

  • Markdown.serializer (Callable[Element]) –

    The serializer set by set_output_format.

  • Markdown.preprocessors (Registry) –

    A collection of preprocessors.

  • Markdown.parser (BlockParser) –

    A collection of blockprocessors.

  • Markdown.inlinePatterns (Registry) –

    A collection of inlinepatterns.

  • Markdown.treeprocessors (Registry) –

    A collection of treeprocessors.

  • Markdown.postprocessors (Registry) –

    A collection of postprocessors.

Other Parameters:

  • extensions (list[Extension | str]) –

    A list of extensions.

    If an item is an instance of a subclass of markdown.extensions.Extension, the instance will be used as-is. If an item is of type str, it is passed to build_extension with its corresponding extension_configs and the returned instance of markdown.extensions.Extension is used.

  • extension_configs (dict[str, dict[str, Any]]) –

    Configuration settings for extensions.

  • output_format (str) –

    Format of output. Supported formats are:

    • xhtml: Outputs XHTML style tags. Default.
    • html: Outputs HTML style tags.
  • tab_length (int) –

    Length of tabs in the source. Default: 4

Methods:

  • build_parser –

    Build the parser from the various parts.

  • registerExtensions –

    Load a list of extensions into an instance of the Markdown class.

  • build_extension –

    Build extension from a string name, then return an instance using the given configs.

  • registerExtension –

    Register an extension as having a resettable state.

  • reset –

    Resets all state variables to prepare the parser instance for new input.

  • set_output_format –

    Set the output format for the class instance.

  • is_block_level –

    Check if the given tag is a block level HTML tag.

  • convert –

    Convert a Markdown string to a string in the specified output format.

  • convertFile –

    Converts a Markdown file and returns the HTML as a Unicode string.

‹› markdown.Markdown.output_formats: dict[str, Callable[[Element], str]] class-attribute

A mapping of known output formats by name and their respective serializers. Each serializer must be a callable which accepts an Element and returns a str.

Defined Value:

output_formats: ClassVar[dict[str, Callable[[Element], str]]] = {
    'html':   to_html_string,
    'xhtml':  to_xhtml_string,
}

‹› markdown.Markdown.ESCAPED_CHARS: list[str] instance-attribute

List of characters which get the backslash escape treatment.

Defined Value:

self.ESCAPED_CHARS: list[str] = [
    '\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '>', '#', '+', '-', '.', '!'
]

‹› markdown.Markdown.build_parser() -> Markdown

Build the parser from the various parts.

Assigns a value to each of the following attributes on the class instance:

This method could be redefined in a subclass to build a custom parser which is made up of a different combination of processors and patterns.

‹› markdown.Markdown.registerExtensions(extensions: Sequence[Extension | str], configs: Mapping[str, dict[str, Any]]) -> Markdown

Load a list of extensions into an instance of the Markdown class.

Parameters:

‹› markdown.Markdown.build_extension(ext_name: str, configs: Mapping[str, Any]) -> Extension

Build extension from a string name, then return an instance using the given configs.

Parameters:

  • ext_name (str) –

    Name of extension as a string.

  • configs (Mapping[str, Any]) –

    Configuration settings for extension.

Returns:

  • Extension –

    An instance of the extension with the given configuration settings.

First attempt to load an entry point. The string name must be registered as an entry point in the markdown.extensions group which points to a subclass of the markdown.extensions.Extension class. If multiple distributions have registered the same name, the first one found is returned.

If no entry point is found, assume dot notation (path.to.module:ClassName). Load the specified class and return an instance. If no class is specified, import the module and call a makeExtension function and return the markdown.extensions.Extension instance returned by that function.

‹› markdown.Markdown.registerExtension(extension: Extension) -> Markdown

Register an extension as having a resettable state.

Parameters:

  • extension (Extension) –

    An instance of the extension to register.

This should get called once by an extension during setup. A “registered” extension’s reset method is called by Markdown.reset(). Not all extensions have or need a resettable state, and so it should not be assumed that all extensions are “registered.”

‹› markdown.Markdown.reset() -> Markdown

Resets all state variables to prepare the parser instance for new input.

Called once upon creation of a class instance. Should be called manually between calls to Markdown.convert.

‹› markdown.Markdown.set_output_format(format: str) -> Markdown

Set the output format for the class instance.

Parameters:

  • format (str) –

    Must be a known value in Markdown.output_formats.

‹› markdown.Markdown.is_block_level(tag: Any) -> bool

Check if the given tag is a block level HTML tag.

Returns True for any string listed in Markdown.block_level_elements. A tag which is not a string always returns False.

‹› markdown.Markdown.convert(source: str) -> str

Convert a Markdown string to a string in the specified output format.

Parameters:

  • source (str) –

    Markdown formatted text as Unicode or ASCII string.

Returns:

  • str –

    A string in the specified output format.

Markdown parsing takes place in five steps:

  1. A bunch of preprocessors munge the input text.
  2. A BlockParser parses the high-level structural elements of the pre-processed text into an ElementTree object.
  3. A bunch of treeprocessors are run against the ElementTree object. One such treeprocessor (markdown.treeprocessors.InlineProcessor) runs inlinepatterns against the ElementTree object, parsing inline markup.
  4. Some postprocessors are run against the text after the ElementTree object has been serialized into text.
  5. The output is returned as a string.

‹› markdown.Markdown.convertFile(input: str | BinaryIO | None = None, output: str | BinaryIO | None = None, encoding: str | None = None) -> Markdown

Converts a Markdown file and returns the HTML as a Unicode string.

Decodes the file using the provided encoding (defaults to utf-8), passes the file content to markdown, and outputs the HTML to either the provided stream or the file with provided name, using the same encoding as the source file. The xmlcharrefreplace error handler is used when encoding the output.

Note: This is the only place that decoding and encoding of Unicode takes place in Python-Markdown. (All other code is Unicode-in / Unicode-out.)

Parameters:

  • input (str | BinaryIO | None, default: None ) –

    File object or path. Reads from stdin if None.

  • output (str | BinaryIO | None, default: None ) –

    File object or path. Writes to stdout if None.

  • encoding (str | None, default: None ) –

    Encoding of input and output files. Defaults to utf-8.

‹› markdown.markdown(text: str, **kwargs: Any) -> str

Convert a markdown string to HTML and return HTML as a Unicode string.

This is a shortcut function for Markdown class to cover the most basic use case. It initializes an instance of Markdown, loads the necessary extensions and runs the parser on the given text.

Parameters:

  • text (str) –

    Markdown formatted text as Unicode or ASCII string.

Other Parameters:

  • **kwargs (Any) –

    Any arguments accepted by the Markdown class.

Returns:

  • str –

    A string in the specified output format.

‹› markdown.markdownFromFile(**kwargs: Any)

Read Markdown text from a file and write output to a file or a stream.

This is a shortcut function which initializes an instance of Markdown, and calls the convertFile method rather than convert.

Other Parameters:

  • input (str | BinaryIO) –

    A file name or readable object.

  • output (str | BinaryIO) –

    A file name or writable object.

  • encoding (str) –

    Encoding of input and output.

  • **kwargs (Any) –

    Any arguments accepted by the Markdown class.