markdownify Documentation

To implement custom conversion logic, inherit from MarkdownConverter and override specific tag methods. The method naming convention is convert_{tag_name}(self, el, text, parent_tags).

For example, to add extra newlines after images or to ignore specific tags like paragraphs, you can override convert_img or convert_p respectively.

from markdownify import MarkdownConverter

class ImageBlockConverter(MarkdownConverter):
    """
    Create a custom MarkdownConverter that adds two newlines after an image
    """
    def convert_img(self, el, text, parent_tags):
        return super().convert_img(el, text, parent_tags) + '\n\n'

# Usage
def md(html, **options):
    return ImageBlockConverter(**options).convert(html)

class IgnoreParagraphsConverter(MarkdownConverter):
    """
    Create a custom MarkdownConverter that ignores paragraphs
    """
    def convert_p(self, el, text, parent_tags):
        return ''

# Usage
def md(html, **options):
    return IgnoreParagraphsConverter(**options).convert(html)

You can customize the conversion behavior by passing options to markdownify() or by instantiating MarkdownConverter directly.

Common Configuration Options:

• autolinks (bool): Whether to use shortcut syntax for autolinks. Defaults to True.
• bs4_options (dict or str): Options passed to BeautifulSoup. Defaults to 'html.parser'.
• bullets (iterable): Characters used for list bullets. Defaults to '*+-'.
• code_language (str): Language identifier for code blocks. Defaults to ''.
• code_language_callback (callable): A function that takes an element and returns a language string.
• convert (list of str): A whitelist of tags to convert. If provided, only these tags are converted.
• escape_asterisks (bool): Whether to escape * characters. Defaults to True.
• escape_underscores (bool): Whether to escape _ characters. Defaults to True.
• escape_misc (bool): Whether to escape miscellaneous special Markdown characters.
• heading_style (str): Style for headings. Options: 'atx', 'atx_closed', or 'underlined' (also known as 'setext').
• newline_style (str): Style for line breaks. Options: 'spaces' or 'backslash'.
• strong_em_symbol (str): The symbol used for strong/emphasis. Defaults to '*'.
• strip (list of str): A blacklist of tags to strip from the output.
• strip_document (str): How to strip leading/trailing newlines from the document. Options: 'lstrip', 'rstrip', 'strip', or None.
• strip_pre (str): How to strip leading/trailing newlines from <pre> blocks. Options: 'lstrip', 'rstrip', 'strip', 'strip_one', or None.
• wrap (bool): Whether to wrap text. Defaults to False.
• wrap_width (int): The width at which to wrap text if wrap is True.

Note: You cannot specify both strip (blacklist) and convert (whitelist) at the same time.

The following options can be passed as keyword arguments to the markdownify() function to control the conversion process:

• strip: A list of tags to strip. Cannot be used with convert.
• convert: A list of tags to convert. Cannot be used with strip.
• autolinks: Boolean. If True, uses "automatic link" style when an <a> tag's content matches its href. Defaults to True.
• default_title: Boolean. If True, sets the link title to its href if no title is provided. Defaults to False.
• heading_style: Defines heading conversion. Accepted values: ATX, ATX_CLOSED, SETEXT, and UNDERLINED (alias for SETEXT). Defaults to UNDERLINED.
• bullets: An iterable (string, list, or tuple) of bullet styles. If one item, it's used for all levels. Otherwise, it alternates by nesting level. Defaults to '*+-'.
• strong_em_symbol: Choose between ASTERISK (default) or UNDERSCORE for strong/emphasized text.
• sub_symbol, sup_symbol: Characters surrounding <sub> and <sup> text. Defaults to empty string.
• newline_style: Defines <br> conversion. SPACES (default) uses two spaces and a newline; BACKSLASH uses \n.
• code_language: String. Assumed language for all <pre> sections. Defaults to ''.
• code_language_callback: A function that takes a BeautifulSoup object and returns a string (the language) or None. Used to extract language from tags (e.g., classes).
• escape_asterisks: Boolean. If False, does not escape * to \*. Defaults to True.
• escape_underscores: Boolean. If False, does not escape _ to \_. Defaults to True.
• escape_misc: Boolean. If True, escapes miscellaneous punctuation. Defaults to False.
• keep_inline_images_in: A list of parent tags (e.g., ['td']) that allow images to be converted to markdown images instead of alt-text.
• table_infer_header: Boolean. If True, uses the first body row as the header if no <thead> is present. Defaults to False.
• wrap, wrap_width: If wrap is True, wraps text at wrap_width (default 80). wrap_width=None reflows to unlimited length.
• strip_document: Controls leading/trailing newlines. Values: LSTRIP, RSTRIP, STRIP (default), or None.
• strip_pre: Controls leading/trailing blank lines in <pre> tags. Values: STRIP (default), STRIP_ONE, or None.
• bs4_options: Configuration for the underlying BeautifulSoup object. Can be a string/list for features or a dictionary for kwargs.

The following table lists the available command-line arguments for the markdownify tool: