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. This gives every code block full ANSI color rendering: compound tokens like Token.Ansi.Bold.Cyan are decomposed into individual CSS classes, and the stylesheet includes rules for the 256-color indexed palette and all SGR text attributes.

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

For Python console sessions:

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

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.

class click_extra.mkdocs.AnsiColorPlugin[source]

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 the stylesheet includes 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)[source]

Patch pymdownx.highlight formatters before page processing begins.

Return type:

MkDocsConfig