Skip to content

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.

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

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

Here is some code: 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.

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

\(p(x|y) = \frac{p(y|x)p(x)}{p(y)}\)

Tip

For more indepth information on how to reproduce the example above, check out Arithmatex Documentation .

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:

Keys Description
name The language name that is specified when using the fence in Markdown. If given *, it will override the base inline logic, the default for all inline names not handled by other custom inlines.
class The class name assigned to the HTML element when converting from Markdown to HTML.
format A function that formats the HTML output. The function should return either an ElementTree object or a string as HTML.

New in 7.0

Starting in 7.0, you can override the base inline logic (the syntax highlighter) by specifying the custom inline with a name of *. This means that if an inline does not match any other custom inline, the default, fallback inline would be handled by your custom * inline. This can be useful for tailoring a inline for a specific, favorite JavaScript highlighter.

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 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

New 9.5

InlineHiliteException added in 9.5

Options

Option Type Default Description
css_class string '' Class name is applied to the wrapper element of the code. If configured, this setting will override the css_class option of Highlight. If nothing is configured here or via or Highlight, the class highlight will be used.
style_plain_text bool | string False When guess_lang is set to False, InlineHilite will avoid applying classes to code blocks that do not explicitly set a language. If it is desired to have plain text styled like code, enable this to inject classes so that they can all be styled the same. By default, plain text is assumed, but if this option is set to a language string, the specified language will be used for any inline code blocks that does not explicitly set a language.
custom_inline [dictionary] [] Custom inline code blocks.

New 10.7

style_plain_text now allows specifying a default language to be assumed.