mkdocs-material/docs/guides/syntax-highlighting.md

template
overrides/main.html

Syntax highlighting

Code blocks and examples are an essential part of technical project documentation. Material for MkDocs provides different ways to set up syntax highlighting for code blocks, either during build time using Pygments or during runtime using a JavaScript syntax highlighter.

Configuration

Highlight

:octicons-file-code-24: Source · :octicons-workflow-24: Extension

The highlight extension, which is part of Python Markdown Extensions, integrates with Material for MkDocs and provides several options for configuring syntax highlighting of code blocks:

use_pygments

This option allows to control whether highlighting should be carried out during build time by Pygments (default, recommended) or runtime with a JavaScript highlighter. Remember to add the necessary additional stylesheets and JavaScript if you want to use the latter:

=== "Pygments"

``` yaml
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
```

=== "JavaScript"

``` yaml
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: false
```

??? example "Syntax highlighting with Highlight.js"

Highlight.js can be integrated by including the respective stylesheet
and JavaScript from a [CDN][8] in `mkdocs.yml`:

``` yaml
extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
extra_css:
  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css
```

Additionally, the following function must be called:

``` js
hljs.initHighlighting()
```