MkDocs¶

MkDocs does not enable Pygments by default.

However, you can activate Pygments syntax highlighting by enabling the appropriate Markdown extensions.

Configuration¶

You can enable Pygments syntax highlighting by using the Markdown extension pymdownx.highlight and setting use_pygments: true.

mkdocs.yml¶

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

Additionally, to enable syntax highlighting for Markdown fenced code blocks, you must include the pymdownx.superfences extension.

By default, MkDocs uses Highlight.js for code highlighting. To use Pygments instead, you must first disable Highlight.js.

mkdocs.yml¶

theme:
  name: mkdocs
  locale: en
  highlightjs: false

Unlike Sphinx, MkDocs does not automatically include Pygments CSS styles. To enable proper code highlighting, you need to add the CSS file manually.

Choose a Pygments style and generate the corresponding CSS file. For example, to generate CSS using the github-light-default style:

pygmentize -S github-light-default -f html -a .highlight > css/pygments.css

Add the generated CSS file to your MkDocs configuration so that it is included in your site:

mkdocs.yml¶

extra_css:
  - css/pygments.css

Make sure to place the CSS file in the correct path (e.g., docs/css/pygments.css) so that MkDocs can find it.