MkDocs

MkDocs can render ANSI-colored terminal output using Click Extra’s Pygments lexers. Without this, raw escape codes show up as garbage text in documentation.

Important

For these helpers to work, you need to install click_extra’s additional dependencies from the mkdocs extra group:

$ pip install click-extra[mkdocs]

Setup

Once Click Extra is installed, enable the plugin in your mkdocs.yml:

mkdocs.yml

markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.superfences

plugins:
  - click-extra

The plugin patches pymdownx.highlight’s formatter classes to use AnsiHtmlFormatter, the same way the Sphinx integration patches PygmentsBridge. Compound tokens like Token.Ansi.Bold.Cyan are decomposed into individual CSS classes. Because MkDocs (unlike Sphinx) never regenerates a Pygments stylesheet from the active formatter, the plugin also generates one covering the 256-color indexed palette and all SGR text attributes, and registers it through extra_css so every page picks up the colors automatically.

ANSI shell sessions

Use Click Extra’s ansi- prefixed lexers as the language identifier in fenced code blocks. The lexer names map directly to Pygments IDs registered via entry points, so MkDocs picks them up automatically.

For terminal sessions with colored output, ansi-shell-session is the most common:

```ansi-shell-session
$ my-cli --help
[1mUsage:[0m [97mmy-cli[0m [36m[2m[OPTIONS][0m [36m[2mCOMMAND[0m [36m[2m[ARGS][0m...

  Manage recipes and shopping lists.

[1mOptions:[0m
  [36m--name[0m [36m[2mTEXT[0m    Your name.
  [36m--help[0m          Show this message and exit.
```

With the plugin enabled, that source renders in full color:

$ my-cli --help
Usage: my-cli [OPTIONS] COMMAND [ARGS]...

  Manage recipes and shopping lists.

Options:
  --name TEXT    Your name.
  --help          Show this message and exit.

For Python console sessions:

```ansi-pycon
>>> print("\033[1;32mHarvest ready!\033[0m Check your garden.")
[1;32mHarvest ready![0m Check your garden.
```

And the Python console example renders as:

>>> print("\033[1;32mHarvest ready!\033[0m Check your garden.")
Harvest ready! Check your garden.

See the full list of available ANSI lexer variants.

mkdocs-click integration

mkdocs-click auto-generates CLI reference pages from Click command objects. If your CLI emits ANSI-styled help text (through Rich, Click Extra, or custom HelpFormatter subclasses), mkdocs-click captures the escape codes verbatim and injects them into the page. Without an ANSI-aware formatter, those codes render as garbled text:

[1mbump-my-version[0m [[1;36mOPTIONS[0m] [1;36mCOMMAND[0m [[1;36mARGS[0m]...

When the click-extra plugin is enabled (as shown in Setup) and mkdocs-click is installed, the plugin automatically patches mkdocs-click’s code-block generators to use the ansi-output lexer instead of plain text. No extra configuration is needed: the usage and options blocks will render with proper ANSI colors.

click_extra.mkdocs API

MkDocs plugin for ANSI color rendering in code blocks.

Patches pymdownx.highlight’s formatter classes so that Token.Ansi.* tokens produced by Click Extra’s Pygments lexers are decomposed into individual CSS classes and styled with the correct colors.

Decomposing tokens into classes only strips the raw escape codes: the classes carry no color until a matching stylesheet is present. Unlike Sphinx’s PygmentsBridge, which regenerates pygments.css from the active formatter on every build, MkDocs never emits one for these classes. The plugin therefore writes the ANSI rules to a dedicated stylesheet (_ansi_stylesheet) and registers it in extra_css so every page links it.

When mkdocs-click is installed, the plugin also patches its code-block generators to use the ansi-output lexer instead of plain text, so that CLI help text with ANSI escape codes renders with colors.

Note

This is the MkDocs counterpart of the Sphinx integration in click_extra.sphinx, which achieves the same result by replacing sphinx.highlighting.PygmentsBridge.html_formatter.

click_extra.mkdocs.ANSI_OUTPUT_FENCE = '```ansi-output'

Fenced code-block opening that triggers the ANSI-aware Pygments lexer.

click_extra.mkdocs.TEXT_FENCE = '```text'

Fenced code-block opening used by mkdocs-click for CLI help output.

click_extra.mkdocs.ANSI_STYLESHEET = 'assets/click-extra/ansi.css'

Site-relative path of the generated ANSI color stylesheet.

Registered in the MkDocs config’s extra_css by AnsiColorPlugin.on_config() so every page links it, and written into the build output by AnsiColorPlugin.on_post_build().

class click_extra.mkdocs.AnsiColorPlugin

Bases: BasePlugin

MkDocs plugin that adds ANSI color support to Pygments code blocks.

Monkey-patches pymdownx.highlight’s block and inline formatter classes to inherit from AnsiHtmlFormatter. This gives every code block in the MkDocs site full ANSI color rendering: compound tokens like Token.Ansi.Bold.Cyan are decomposed into individual CSS classes, and a generated stylesheet (written by on_post_build() and registered in extra_css by on_config()) supplies the color rules for the 256-color indexed palette and all SGR text attributes.

When mkdocs-click is installed, its code-block generators are also patched to use the ansi-output lexer so that CLI help text renders with colors.

on_config(config)

Patch pymdownx.highlight formatters and register the ANSI stylesheet.

Runs before page processing begins. Appending ANSI_STYLESHEET to extra_css makes MkDocs link it from every page (resolving the relative path per page, including under use_directory_urls). The file itself is written later, in on_post_build().

Return type:

MkDocsConfig

on_post_build(config)

Write the ANSI color stylesheet into the built site.

The formatters patched in on_config() emit -Ansi-* CSS classes, but MkDocs, unlike Sphinx’s PygmentsBridge, never regenerates a Pygments stylesheet from the active formatter. Without this file the classes have no color rules and terminal output renders colorless. Runs after the theme has copied its own assets, so the file survives the site-directory cleanup.

Return type:

None