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

## ‹› `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`][xml.etree.ElementTree.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`

### ‹› `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`][xml.etree.ElementTree.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`][xml.etree.ElementTree.ElementTree] object.
3. A bunch of `treeprocessors` are run against the [`ElementTree`][xml.etree.ElementTree.ElementTree] object. One such `treeprocessor` (`markdown.treeprocessors.InlineProcessor`) runs `inlinepatterns` against the [`ElementTree`][xml.etree.ElementTree.ElementTree] object, parsing inline markup.
4. Some `postprocessors` are run against the text after the [`ElementTree`][xml.etree.ElementTree.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.