# ‹› `` `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:

- `core` –

  Core functionality.

- `preprocessors` –

  Pre-processors.

- `blockparser` –

  Core Markdown block parser.

- `blockprocessors` –

  Block processors.

- `treeprocessors` –

  Tree processors.

- `inlinepatterns` –

  Inline patterns.

- `postprocessors` –

  Post-processors.

- `serializers` –

  Serializers.

- `util` –

  Utility functions.

- `htmlparser` –

  HTML parser.

- `test_tools` –

  Testing utilities.

- `extensions` –

  Markdown extensions.

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 or stream and write HTML output to a file or 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` –

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

### ‹› `` `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:

- `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`.

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:

- `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 `configs` and the returned instance of `markdown.extensions.Extension` is used.

- `configs` (`dict[str, dict[str, Any]]`) –

  Configuration settings for extensions.

### ‹› `` `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.

Warning

The Python-Markdown library does not sanitize its HTML output. If you are processing Markdown input from an untrusted source, it is your responsibility to ensure that it is properly sanitized. For more information see Sanitizing HTML Output.

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

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

Decodes the input 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`.

Warning

The Python-Markdown library does not sanitize its HTML output. As `Markdown.convertFile` writes directly to the file system, there is no easy way to sanitize the output from Python code. Therefore, it is recommended that the `Markdown.convertFile` method not be used on input from an untrusted source. For more information see Sanitizing HTML Output.

## ‹› `` `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.

Warning

The Python-Markdown library does not sanitize its HTML output. If you are processing Markdown input from an untrusted source, it is your responsibility to ensure that it is properly sanitized. For more information see Sanitizing HTML Output.

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

Read Markdown text from a file or stream and write HTML output to a file or 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.

Warning

The Python-Markdown library does not sanitize its HTML output. As `markdown.markdownFromFile` writes directly to the file system, there is no easy way to sanitize the output from Python code. Therefore, it is recommended that the `markdown.markdownFromFile` function not be used on input from an untrusted source. For more information see Sanitizing HTML Output.