‹› markdown.extensions.codehilite

Adds code/syntax highlighting to standard Python-Markdown code blocks.

See the documentation for details.

‹› markdown.extensions.codehilite.parse_hl_lines(expr: str) -> list[int]

Support our syntax for emphasizing certain lines of code.

expr should be like ‘1 2’ to emphasize lines 1 and 2 of a code block. Returns a list of integers, the line numbers to emphasize.

‹› markdown.extensions.codehilite.CodeHilite(src: str, **options)

Determine language of source code, and pass it on to the Pygments highlighter.

Usage:

code = CodeHilite(src=some_code, lang='python')
html = code.hilite()

Parameters:

  • src (str) –

    Source string or any object with a .readline attribute.

Other Parameters:

  • lang (str) –

    String name of Pygments lexer to use for highlighting. Default: None.

  • guess_lang (bool) –

    Auto-detect which lexer to use. Ignored if lang is set to a valid value. Default: True.

  • use_pygments (bool) –

    Pass code to Pygments for code highlighting. If False, the code is instead wrapped for highlighting by a JavaScript library. Default: True.

  • pygments_formatter (str) –

    The name of a Pygments formatter or a formatter class used for highlighting the code blocks. Default: html.

  • linenums (bool) –

    An alias to Pygments linenos formatter option. Default: None.

  • css_class (str) –

    An alias to Pygments cssclass formatter option. Default: ‘codehilite’.

  • lang_prefix (str) –

    Prefix prepended to the language. Default: “language-“.

Other Options:

Any other options are accepted and passed on to the lexer and formatter. Therefore, valid options include any options which are accepted by the html formatter or whichever lexer the code’s language uses. Note that most lexers do not have any options. However, a few have very useful options, such as PHP’s startinline option. Any invalid options are ignored without error.

Additionally, when Pygments is enabled, the code’s language is passed to the formatter as an extra option lang_str, whose value being {lang_prefix}{lang}. This option has no effect to the Pygments’ builtin formatters.

Advanced Usage:

code = CodeHilite(
    src = some_code,
    lang = 'php',
    startinline = True,      # Lexer option. Snippet does not start with `<?php`.
    linenostart = 42,        # Formatter option. Snippet starts on line 42.
    hl_lines = [45, 49, 50], # Formatter option. Highlight lines 45, 49, and 50.
    linenos = 'inline'       # Formatter option. Avoid alignment problems.
)
html = code.hilite()

‹› markdown.extensions.codehilite.CodeHilite.hilite(shebang: bool = True) -> str

Pass code to the Pygments highlighter with optional line numbers. The output should then be styled with CSS to your liking. No styles are applied by default - only styling hooks (i.e.: <span class="k">).

returns : A string of html.

‹› markdown.extensions.codehilite.HiliteTreeprocessor(md: Markdown | None = None)

Bases: Treeprocessor

Highlight source code in code blocks.

‹› markdown.extensions.codehilite.HiliteTreeprocessor.code_unescape(text: str) -> str

Unescape code.

‹› markdown.extensions.codehilite.HiliteTreeprocessor.run(root: etree.Element) -> None

Find code blocks and store in htmlStash.

‹› markdown.extensions.codehilite.CodeHiliteExtension(**kwargs)

Bases: Extension

Add source code highlighting to markdown code blocks.

‹› markdown.extensions.codehilite.CodeHiliteExtension.config instance-attribute

Default configuration options.

Defined Value:

self.config = {
    'linenums': [
        None, "Use lines numbers. True|table|inline=yes, False=no, None=auto. Default: `None`."
    ],
    'guess_lang': [
        True, "Automatic language detection - Default: `True`."
    ],
    'css_class': [
        "codehilite", "Set class name for wrapper <div> - Default: `codehilite`."
    ],
    'pygments_style': [
        'default', 'Pygments HTML Formatter Style (Colorscheme). Default: `default`.'
    ],
    'noclasses': [
        False, 'Use inline styles instead of CSS classes - Default `False`.'
    ],
    'use_pygments': [
        True, 'Highlight code blocks with pygments. Disable if using a JavaScript library. Default: `True`.'
    ],
    'lang_prefix': [
        'language-', 'Prefix prepended to the language when `use_pygments` is false. Default: `language-`.'
    ],
    'pygments_formatter': [
        'html', 'Use a specific formatter for Pygments highlighting. Default: `html`.'
    ],
}

‹› markdown.extensions.codehilite.CodeHiliteExtension.extendMarkdown(md)

Add HilitePostprocessor to Markdown instance.