# Python Markdown Extensions

The [Python Markdown Extensions](<https://facelessuser.github.io/pymdown-extensions/>) package is an excellent collection of additional extensions perfectly suited for advanced technical writing. Zensical lists this package as an explicit dependency, so it's automatically installed with a supported version.

## Supported extensions

In general, all extensions that are part of [Python Markdown Extensions](<https://facelessuser.github.io/pymdown-extensions/>) should work with Zensical. The following list includes all extensions that are natively supported, meaning they work without any further adjustments.

### Arithmatex

The [Arithmatex](<https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/>) extension allows for rendering of block and inline block equations and integrates seamlessly with [MathJax](<https://www.mathjax.org/>)[^/docs/compatibility/markdown/python-markdown-extensions/#1] – a library for mathematical typesetting. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.arithmatex.generic = true
```

```yaml
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
```

Besides enabling the extension in your configuration, a MathJax configuration and the JavaScript runtime need to be included, which can be done with a few lines of [additional JavaScript](<https://zensical.org/docs/customization/#additional-javascript>):

```js
window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

component$.subscribe(({ ref }) => {
  if (ref.classList.contains("md-annotation"))
    MathJax.typesetPromise([ref])
})
```

1. This integrates MathJax with [instant navigation](<https://zensical.org/docs/setup/navigation/#instant-navigation>)

```toml
[project]
extra_javascript = [
  "javascripts/mathjax.js",
  "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js",
]
```

```yaml
extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
```

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See these authoring guides for usage:

- [Using block syntax](<https://zensical.org/docs/authoring/math/#use-block-syntax>)
- [Using inline block syntax](<https://zensical.org/docs/authoring/math/#use-inline-block-syntax>)

### Caption

The [Caption](<https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/>) extension adds the ability to add captions to any Markdown block, including images, tables, and code blocks. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.blocks.caption = {}
```

```yaml
markdown_extensions:
  - pymdownx.blocks.caption
```

The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [Caption documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/>) for more information.

### Caret, Mark &amp; Tilde

The [Caret](<https://facelessuser.github.io/pymdown-extensions/extensions/caret/>), [Mark](<https://facelessuser.github.io/pymdown-extensions/extensions/mark/>) and [Tilde](<https://facelessuser.github.io/pymdown-extensions/extensions/tilde/>) extensions add the ability to highlight text and define sub- and superscript using a simple syntax. Enable them together via:

```toml
[project.markdown_extensions]
pymdownx.caret = {}
pymdownx.mark = {}
pymdownx.tilde = {}
```

```yaml
markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
```

The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [Caret](<https://facelessuser.github.io/pymdown-extensions/extensions/caret/>), [Mark](<https://facelessuser.github.io/pymdown-extensions/extensions/mark/>) and [Tilde documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/tilde/>) for guidance.

See these authoring guides for usage:

- [Highlighting text](<https://zensical.org/docs/authoring/formatting/#highlight-text>)
- [Sub- and superscripts](<https://zensical.org/docs/authoring/formatting/#sub-and-superscripts>)

### Details

The [Details](<https://facelessuser.github.io/pymdown-extensions/extensions/details/>) extension supercharges the [Admonition](<https://zensical.org/docs/compatibility/markdown/python-markdown/#admonition>) extension, making the resulting *call-outs* collapsible, allowing them to be opened and closed by the user. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.details = {}
```

```yaml
markdown_extensions:
  - pymdownx.details
```

No configuration options are available. See this authoring guide for usage:

- [Collapsible blocks](<https://zensical.org/docs/authoring/admonitions/#collapsible-blocks>)

### Emoji

The [Emoji](<https://facelessuser.github.io/pymdown-extensions/extensions/emoji/>) extension automatically inlines bundled and custom icons and emojis in `*.svg` file format into the resulting HTML page. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.emoji.emoji_generator = "zensical.extensions.emoji.to_svg"
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji" # (1)!
```

1. [Python Markdown Extensions](<https://facelessuser.github.io/pymdown-extensions/>) uses the `pymdownx` namespace, but in order to support the inlining of icons, the `zensical` namespace must be used, as it extends the functionality of `pymdownx`.

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji # (1)!
      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
```

1. [Python Markdown Extensions](<https://facelessuser.github.io/pymdown-extensions/>) uses the `pymdownx` namespace, but in order to support the inlining of icons, the `zensical` namespace must be used, as it extends the functionality of `pymdownx`.

The following configuration options are supported:

#### `emoji_index`

This option defines which set of emojis is used for rendering. Note that the use of `emojione` is not recommended due to [restrictions in licensing](<https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes>):

```toml
[project.markdown_extensions]
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji"
```

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
```

#### `emoji_generator`

This option defines how the resolved emoji or icon shortcode is rendered. Note that icons can only be used together with the `to_svg` configuration:

```toml
[project.markdown_extensions]
pymdownx.emoji.emoji_generator = "zensical.extensions.emoji.to_svg"
```

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
```

#### `custom_icons`

This option allows to list folders with additional icon sets to be used in Markdown or the configuration, which is explained in more detail in the [icon customization guide](<https://zensical.org/docs/setup/logo-and-icons/#additional-icons>):

```toml
[project.markdown_extensions]
pymdownx.emoji.emoji_generator = "zensical.extensions.emoji.to_svg"
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji"
pymdownx.emoji.options.custom_icons = [
  "overrides/.icons",
]
```

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons
```

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See usage:

- [Using emojis](<https://zensical.org/docs/authoring/icons-emojis/#use-emojis>)
- [Using icons](<https://zensical.org/docs/authoring/icons-emojis/#use-icons>)
- [Using icons in templates](<https://zensical.org/docs/authoring/icons-emojis/#use-icons-in-templates>)

### Highlight

The [Highlight](<https://facelessuser.github.io/pymdown-extensions/extensions/highlight/>) extension adds support for syntax highlighting of code blocks (with the help of [SuperFences](<#superfences>)) and inline code blocks (with the help of [InlineHilite](<#inlinehilite>)). Enable it via:

```toml
[project.markdown_extensions]
pymdownx.highlight.anchor_linenums = true
pymdownx.superfences = {}
```

1. [Highlight](<https://facelessuser.github.io/pymdown-extensions/extensions/highlight/>) is used by the [SuperFences](<#superfences>) extension to perform syntax highlighting on code blocks, not the other way round, which is why this extension also needs to be enabled.

```yaml
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences # (1)!
```

1. [Highlight](<https://facelessuser.github.io/pymdown-extensions/extensions/highlight/>) is used by the [SuperFences](<#superfences>) extension to perform syntax highlighting on code blocks, not the other way round, which is why this extension also needs to be enabled.

The following configuration options are supported:

#### `pygments_lang_class`

This option instructs [Pygments](<https://pygments.org>) to add a CSS class to identify the language of the code block, which is essential for custom annotation markers to function. Enable via:

```toml
[project.markdown_extensions]
pymdownx.highlight.pygments_lang_class = true
```

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

#### `auto_title`

This option will automatically add a [title](<https://zensical.org/docs/authoring/code-blocks/#add-a-title>) to all code blocks that shows the name of the language being used, e.g. `Python` is printed for a `py` block:

```toml
[project.markdown_extensions]
pymdownx.highlight.auto_title = true
```

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

#### `linenums`

This option will add line numbers to *all* code blocks. If you wish to add line numbers to *some*, but not all code blocks, consult the section on [adding line numbers](<https://zensical.org/docs/authoring/code-blocks/#add-line-numbers>) in the code block section, which also contains some tips on working with line numbers:

```toml
[project.markdown_extensions]
pymdownx.highlight.linenums = true
```

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

#### `linenums_style`

The [Highlight](<https://facelessuser.github.io/pymdown-extensions/extensions/highlight/>) extension provides three ways to add line numbers, two of which are supported by Zensical. While `table` wraps a code block in a `<table>` element, `pymdownx-inline` renders line numbers as part of the line itself:

```toml
[project.markdown_extensions]
pymdownx.highlight.linenums_style = "pymdownx-inline"
```

```yaml
markdown_extensions:
  - pymdownx.highlight:
      linenums_style: pymdownx-inline
```

> [!NOTE]
>
> **Avoid including line numbers in copy-and-paste**
>
> Note that `inline` will put line numbers next to the actual code, which means that they will be included when selecting text with the cursor or copying a code block to the clipboard. Thus, the usage of either `table` or `pymdownx-inline` is recommended.

#### `anchor_linenums`

If a code blocks contains line numbers, enabling this setting will wrap them with anchor links, so they can be hyperlinked and shared more easily:

```toml
[project.markdown_extensions]
pymdownx.highlight.anchor_linenums = true
```

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

#### `line_spans`

When this option is set, each line of a code block is wrapped in a `span`, which is essential for features like line highlighting to work correctly:

```toml
[project.markdown_extensions]
pymdownx.highlight.line_spans = "__span"
```

```yaml
markdown_extensions:
  - pymdownx.highlight:
      line_spans: __span
```

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See these authoring guides for usage:

- [Using code blocks](<https://zensical.org/docs/authoring/code-blocks/#usage>)
- [Adding a title](<https://zensical.org/docs/authoring/code-blocks/#add-a-title>)
- [Adding line numbers](<https://zensical.org/docs/authoring/code-blocks/#add-line-numbers>)
- [Highlighting specific lines](<https://zensical.org/docs/authoring/code-blocks/#highlight-specific-lines>)
- [Custom syntax theme](<https://zensical.org/docs/authoring/code-blocks/#custom-syntax-theme>)

### InlineHilite

The [InlineHilite](<https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/>) extension add support for syntax highlighting of inline code blocks. It's built on top of the [Highlight](<#highlight>) extension, from which it sources its configuration. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.highlight = {}
pymdownx.inlinehilite = {}
```

```yaml
markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite
```

The configuration options of this extension are not specific to Material for MkDocs, as they only impact the Markdown parsing stage. The only exception is the [`css_class`](<https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options>) option, which must not be changed. See the [InlineHilite documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/>) for guidance.

See this authoring guide for usage:

- [Highlighting inline code blocks](<https://zensical.org/docs/authoring/code-blocks/#highlight-inline-code-blocks>)

### Keys

The [Keys](<https://facelessuser.github.io/pymdown-extensions/extensions/keys/>) extension adds a simple syntax to allow for the rendering of keyboard keys and combinations, e.g. <kbd class="key-control">Ctrl</kbd>\+<kbd class="key-alt">Alt</kbd>\+<kbd class="key-delete">Del</kbd>. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.keys = {}
```

```yaml
markdown_extensions:
  - pymdownx.keys
```

The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. The only exception is the [`class`](<https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options>) option, which must not be changed. See the [Keys documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/keys/>) for more information.

See this authoring guide for usage:

- [Adding keyboard keys](<https://zensical.org/docs/authoring/formatting/#add-keyboard-keys>)

### SmartSymbols

The [SmartSymbols](<https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/>) extension converts some sequences of characters into their corresponding symbols, e.g. copyright symbols or fractions. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.smartsymbols = {}
```

```yaml
markdown_extensions:
  - pymdownx.smartsymbols
```

The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [SmartSymbols documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/>) for guidance.

### Snippets

The [Snippets](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/>) extension adds the ability to embed content from arbitrary files into a document, including other documents or source files, by using a simple syntax. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.snippets = {}
```

```yaml
markdown_extensions:
  - pymdownx.snippets
```

The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [Snippets documentation](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/>) for more information.

See these authoring guides for usage:

- [Adding a glossary](<https://zensical.org/docs/authoring/tooltips/#add-a-glossary>)
- [Embedding external files](<https://zensical.org/docs/authoring/code-blocks/#embed-external-files>)

### SuperFences

The [SuperFences](<https://facelessuser.github.io/pymdown-extensions/extensions/superfences/>) extension allows for arbitrary nesting of code and content blocks inside each other, including admonitions, tabs, lists and all other elements. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.superfences = {}
```

```yaml
markdown_extensions:
  - pymdownx.superfences
```

The following configuration options are supported:

#### `custom_fences`

This option allows to define a handler for custom fences, e.g. to preserve the definitions of [Mermaid.js](<https://mermaid-js.github.io/mermaid/>) diagrams to be interpreted in the browser:

```toml
[project.markdown_extensions]
pymdownx.superfences.custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
]
```

```yaml
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
```

Note that this will primarily prevent syntax highlighting from being applied. See the authoring guide for [diagrams](<https://zensical.org/docs/authoring/diagrams/index.md>) to learn how Mermaid.js is integrated with Zensical.

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See these authoring guides for usage:

- [Using code blocks](<https://zensical.org/docs/authoring/code-blocks/#usage>)
- [Using content tabs](<https://zensical.org/docs/authoring/content-tabs/#usage>)
- [Using flowcharts](<https://zensical.org/docs/authoring/diagrams/#use-flowcharts>)
- [Using sequence diagrams](<https://zensical.org/docs/authoring/diagrams/#use-sequence-diagrams>)
- [Using state diagrams](<https://zensical.org/docs/authoring/diagrams/#use-state-diagrams>)
- [Using class diagrams](<https://zensical.org/docs/authoring/diagrams/#use-class-diagrams>)
- [Using entity-relationship diagrams](<https://zensical.org/docs/authoring/diagrams/#use-entity-relationship-diagrams>)

### Tabbed

The [Tabbed](<https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/>) extension allows the usage of content tabs, a simple way to group related content and code blocks under accessible tabs. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.tabbed.alternate_style = true
pymdownx.tabbed.combine_header_slug = true
```

```yaml
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
```

The following configuration options are supported:

#### `alternate_style`

This option enables the content tabs [alternate style](<https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style>), which has [better behavior on mobile viewports](<https://x.com/squidfunk/status/1424740370596958214>), and is the only supported style:

```toml
[project.markdown_extensions]
pymdownx.tabbed.alternate_style = true
```

```yaml
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true
```

#### `combine_header_slug`

This option enables the content tabs' `combine_header_slug` style flag, which prepends the id of the header to the `id` of the tab:

```toml
[project.markdown_extensions]
pymdownx.tabbed.combine_header_slug = true
```

```yaml
markdown_extensions:
  - pymdownx.tabbed:
      combine_header_slug: true
```

#### `slugify`

This option allows for customization of the slug function. For some languages, the default may not produce good and readable identifiers – consider using another slug function like for example those from [Python Markdown Extensions](<https://facelessuser.github.io/pymdown-extensions/extras/slugs/>). To produce all-lowercase slugs:

```toml
[project.markdown_extensions]
pymdownx.tabbed.slugify.object = "pymdownx.slugs.slugify"
pymdownx.tabbed.slugify.kwds.case = "lower"
```

```yaml
markdown_extensions:
  - pymdownx.tabbed:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
```

In order to retain the case of the input:

```toml
[project.markdown_extensions]
pymdownx.tabbed.slugify.object = "pymdownx.slugs.slugify"
```

```yaml
markdown_extensions:
  - pymdownx.tabbed:
      slugify: !!python/object/apply:pymdownx.slugs.slugify {}
```

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See these authoring guides for usage:

- [Grouping code blocks](<https://zensical.org/docs/authoring/content-tabs/#group-code-blocks>)
- [Grouping other content](<https://zensical.org/docs/authoring/content-tabs/#group-other-content>)
- [Embedded content](<https://zensical.org/docs/authoring/content-tabs/#embed-content>)

### Tasklist

The [Tasklist](<https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/>) extension allows for the usage of [GitHub Flavored Markdown](<https://github.github.com/gfm/>) inspired [task lists](<https://github.github.com/gfm/#task-list-items-extension->), following the same syntactical conventions. Enable it via:

```toml
[project.markdown_extensions]
pymdownx.tasklist.custom_checkbox = true
```

```yaml
markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true
```

The following configuration options are supported:

#### `checkbox`

This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, and is therefore recommended:

```toml
[project.markdown_extensions]
pymdownx.tasklist.custom_checkbox = true
```

```yaml
markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true
```

#### `clickable_checkbox`

This option toggles whether checkboxes are clickable. As the state is not persisted, the use of this option is *rather discouraged* from a user experience perspective:

```toml
[project.markdown_extensions]
pymdownx.tasklist.clickable_checkbox = true
```

```yaml
markdown_extensions:
  - pymdownx.tasklist:
      clickable_checkbox: true
```

The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk.

See this authoring guide for usage:

- [Using task lists](<https://zensical.org/docs/authoring/lists/#use-task-lists>)

[^/docs/compatibility/markdown/python-markdown-extensions/#1]: Other libraries like [KaTeX](<https://github.com/Khan/KaTeX>) are also supported and can be integrated with some additional effort. See the [Arithmatex documentation on KaTeX](<https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex>) for further guidance, as this is beyond the scope of Zensical.