InlineHilite

Overview

InlineHilite is an inline code highlighter inspired by CodeHilite. Borrowing from CodeHilite's existing syntax, InlineHilite utilizes the following syntax to insert inline highlighted code: `:::language mycode` or `#!language mycode`. In CodeHilite, #! means "use line numbers", but line numbers will never be used in inline code regardless of which form is used. Use of one form or the other is purely for personal preference. As this feature is discussed further, we will call these specifiers (#! and :::) mock shebangs, mainly due to the first options similar syntax to a real shebang.

Here is some code: `#!py3 import pymdownx; pymdownx.__version__`.

The mock shebang will be treated like text here: ` #!js var test = 0; `.

When using the colon mock shebang, 3 or more colons can be used. Mock shebangs must come immediately after the opening backtick(s) and must be followed by at least one space. If you need to escape a mock shebang, at the start of a code block, just put a space before it, and it will be treated as part of the code.

The InlineHilite extension can be included in Python Markdown by using the following:

import markdown
md = markdown.Markdown(extensions=['pymdownx.inlinehilite'])

Code Highlighting

Assuming Pygments is installed, code highlighting will be handled by Pygments. If Pygments is not installed, or disabled, code blocks will be output for JavaScript syntax highlighters as:

<code class="highlight language-mylanguage"></code>

Highlighting can be further controlled via the pymdownx.highlight extension. You must include pymdownx.highlight in the extensions list in order to be able to configure it.

Using JavaScript Highlighters

If using Pygments, the elements will be highlighted without issues, but you may need to adjust CSS to get the general style of the inline block the way you like it.

If you are using a JavaScript highlighter, such as highlight.js, you will most likely need to construct a JavaScript method to target the inline blocks as these may not be targeted out of the box. You may also find it useful to tag inline code with a different class than what is used for block code so you can also process and style them differently. By default, it uses whatever pymdownx.highlight uses, but this can be configured independently for inline code in the options.

Custom Inline Blocks

Like SuperFences, InlineHilite now provides a support for custom inline blocks.

`#!math p(x|y) = \frac{p(y|x)p(x)}{p(y)}`

Custom inline code blocks are created via the custom_inline option. custom_inline takes an array of dictionaries where each dictionary defines a custom inline code block. The dictionaries requires the following keys:

Formatters

def custom_formatter(source, language, css_class, md):
    return el  # Or string

In general, formatters take four parameters:

1. The source found between the backticks.
2. The specified language.
3. The class name originally defined via the class option in the custom_inline entry.
4. The Markdown class object.

It Should return a either an ElementTree element or a string as HTML. When returning a string, InlineHilite will treat the string as ready for HTML, so escape what needs to be escaped as it is expected to be fully ready HTML and will be stashed and re-inserted at post processing.

When returning an ElementTree object, remember to wrap string content as markdown.util.AtomicString to prevent it from being processed further, you can also stash raw HTML string content assigned to elements like InlineHilite does by default above. InlineHilite will not try and guess what you intend, you must manage your content in the ElementTree objects or the Markdown parser may apply other conversion to your HTML content.

Exception Handling

In general, if an exception occurs in the formatter, InlineHilite will gracefully ignore the formatter. If this occurs, the code content will just be abandoned.

Some users may want such failures to not silently go by. InlineHilite exposes a special exception called InlineHiliteException which, if raised, will not gracefully be handled. If InlineHiliteException is raised, this will bubble all the way up and cause Markdown parsing to halt.

def format_fail(src, language, class_name, md):
    """Inline formatter"""

    raise InlineHiliteException('Fail!')

InlineHiliteException can be used to raise other exceptions if desired.

def format_fail(src, language, class_name, md):
    """Inline formatter"""

    try:
        raise ValueError('Nooo!')
    except ValueError as e:
        raise InlineHiliteException from e

Options