MkDocs Pygments

Highlighting themes for code blocks.

Installation

pip install mkdocs-pygments

Usage

Configure it in mkdocs.yml:

# mkdocs.yml
plugins:
- pygments:
    light: autumn
    dark: github-dark

To know which themes are available, you can either read our docs, or use a theme that doesn't exist, to abort the build with an error and a message listing the available themes:

# mkdocs.yml
plugins:
- pygments:
    light: wodjweofijwqefd
    dark: github-dark

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
ERROR   -  pygments: Unknown theme: 'wodjweofijwqefd'. Available themes:
           abap, algol, algol_nu, arduino, autumn, bw, borland, coffee,
           colorful, default, dracula, emacs, friendly_grayscale, friendly,
           fruity, github-dark, gruvbox-dark, gruvbox-light, igor, inkpot,
           lightbulb, lilypond, lovelace, manni, material, monokai, murphy,
           native, nord-darker, nord, one-dark, paraiso-dark, paraiso-light,
           pastie, perldoc, rainbow_dash, rrt, sas, solarized-dark,
           solarized-light, staroffice, stata-dark, stata-light,
           tango, trac, vim, vs, xcode, zenburn

It's possible to instruct MkDocs Pygments to ignore the background color set by a theme, in order to make it work for both light and dark color schemes.

For example, to use the autumn style (which is a light theme), for both light and dark schemes while adapting the background color:

# mkdocs.yml
plugins:
- pygments:
    light: autumn
    respect_light_background: true  # default value
    dark: autumn
    respect_dark_background: false

To use the github-dark style (which is a dark theme), for both light and dark schemes while adapting the background color:

# mkdocs.yml
plugins:
- pygments:
    light: github-dark
    respect_light_background: false
    dark: github-dark

By default, the background color is respected, so you don't have to actually specify respect_<light/dark>_background: true.

Sponsors