Python-Markdown Documentation

Python-Markdown is a Python implementation of John Gruber's Markdown syntax. It is designed to be used in web server environments, meaning it avoids raising exceptions or writing directly to stdout.

Key Characteristics:

• Not CommonMark: This is not a CommonMark implementation. It follows the original Markdown syntax rules and behavior.
• Unicode Support: Supports any language supported by Unicode, including bi-directional text (e.g., Russian, Arabic).
• Extensible: Provides a public Extension API to modify or extend parser behavior.
• Output Formats: Supports both HTML and XHTML style tags.
• Interfaces: Available as both a Python library and a command-line interface (CLI).

Python-Markdown provides an API for plugging in custom functionality and syntax. Extensions work by patching into specific stages of the parsing pipeline. The processing flow is as follows:

1. Preprocessors: Alter the raw source text before it reaches the parser.
2. Block Processors: Process blocks of text separated by blank lines.
3. Inline Processors: Process inline elements (e.g., *strong*) within the text.
4. Tree Processors: Modify the constructed ElementTree object.
5. Postprocessors: Munge the final Unicode text output just before it is returned.

If the automatic GitHub workflow fails to deploy a release, you can perform manual deployment steps:

1. Deploy to PyPI: Use the make deploy command. You must provide a valid authentication token.
2. Deploy Documentation: Use mkdocs gh-deploy. This assumes the markdown and Python-Markdown.github.io repositories are located in sibling directories.

cd Python-Markdown.github.io
mkdocs gh-deploy --config-file ../markdown/mkdocs.yml --remote-branch master

To convert a Markdown string into HTML, import the markdown module and call the markdown.markdown() function with your input string.

import markdown
html = markdown.markdown(your_text_string)

The SmartyPants extension converts ASCII dashes, quotes, and ellipses into their HTML entity equivalents. To use it, include 'smarty' in the extensions list when calling markdown.markdown().

markdown.markdown(some_text, extensions=['smarty'])

The nl2br extension treats newlines in your Markdown text as hard breaks (<br />), similar to the behavior found in GitHub Flavored Markdown or StackOverflow.

Note: This extension is currently in maintenance mode. It will receive bug fixes and compatibility updates with the core parser, but no new features or behavioral changes will be added.

To use it, include 'nl2br' in the extensions list when calling markdown.markdown().

Fenced code blocks are defined by starting and ending with three or more backticks (`) or tildes (~) on a line by themselves. The closing delimiter must match the opening delimiter in both type and count.

• Backticks:

  code content

• Tildes:

  code content

• Nesting: To include delimiters inside a block, use a higher number of characters for the outer fence.
• Blank Lines: Blank lines at the start or end of the block are preserved.

Limitation: Fenced code blocks are only supported at the document root level and cannot be nested inside lists or blockquotes.

The legacy_attrs extension restores the original Python-Markdown attribute setting syntax used in versions prior to 3.0. This is useful for maintaining compatibility with older documents that use the {@key=value} syntax.

Note: This extension is in maintenance mode. No new features will be added, though bugs will be fixed to maintain compatibility with the core parser.

Python-Markdown organizes processing into several collections. To ensure your extension runs at the correct time relative to built-in features, you must manage priorities within these registries:

• preprocessors
• blockprocessors
• treeprocessors
• inlinepatterns
• postprocessors

Priority Rules:

• Higher number = Higher priority: A processor with priority 100 runs before a processor with priority 50.
• Extensibility: Built-in processors use large gaps between their priority values to allow extensions to insert custom logic without conflicts.
• Conflict Resolution: If your extension conflicts with a third-party one, you may need to inspect the source code of that extension to determine its assigned priority.

If you have a pre-made string of raw HTML (perhaps from a third-party library) that must remain unmodified, use the htmlStash utility. This prevents subsequent processing steps from altering the HTML.

1. Use self.md.htmlStash.store(html_string) to save the raw HTML.
2. This method returns a placeholder string.
3. Insert this placeholder string into your ElementTree instead of the actual HTML.
4. A postprocessor will automatically replace the placeholder with the original raw string during serialization.

Note: For self.md.htmlStash to be available, the markdown.Markdown instance must be passed to your processor (typically via the extendMarkdown method).

import xml.etree.ElementTree as etree

# Inside a processor where self.md is available:
html = "<p>This is some <em>raw</em> HTML data</p>"
el = etree.Element("div")
el.text = self.md.htmlStash.store(html)

The legacy_em extension restores Markdown's original behavior for emphasis (<em>) and strong (<strong>) syntax when using underscores.

By default, Python-Markdown avoids applying emphasis to underscores located inside words (e.g., _connected_words_ becomes <em>connected_words</em>). When using the legacy_em extension, this behavior is changed to match the original Markdown reference implementation (e.g., _connected_words_ becomes <em>connected</em>words_).

Note: This extension is in maintenance mode. It will receive bug fixes and compatibility updates with the core parser, but no new features or behavioral changes will be added.

The meta extension allows you to define document metadata at the beginning of a Markdown file. This metadata is stripped from the final HTML output but is made available via the Meta attribute of the Markdown instance for use in your Python code or other extensions.

To use it, include 'meta' in the extensions list when calling markdown.markdown() or initializing a markdown.Markdown object.