Skip to content

Extensions

Markdown is a very small language with a kind-of reference implementation called John Gruber's Markdown. Python Markdown and Python Markdown Extensions are two packages that enhance the Markdown writing experience, adding useful syntax extensions for technical writing.

We'll be moving to CommonMark soon

Zensical is being actively developed, and we're working towards a more comprehensive module system that will allow us to support CommonMark in the future. Of course, we will provide tools to automatically migrate your existing content when the time comes.

Supported extensions

The following extensions are all supported by Zensical and therefore strongly recommended. Click on each extension to learn about its purpose and configuration:

Configuration

Default configuration

If your configuration file contains no definitions for the extensions then Zensical will use a default configuration that enables the extensions that are commonly used and are unlikely to cause any issues. We recommend that you use the default configuration until you find a reason to change it. This will enable most of the features listed in the Authoring part of this documentation.

If you bootstrap your project with zensical new, the following extensions are enabled by default:

[project.markdown_extensions.abbr]
[project.markdown_extensions.admonition]
[project.markdown_extensions.attr_list]
[project.markdown_extensions.def_list]
[project.markdown_extensions.footnotes]
[project.markdown_extensions.md_in_html]
[project.markdown_extensions.toc]
permalink = true
[project.markdown_extensions.pymdownx.arithmatex]
generic = true
[project.markdown_extensions.pymdownx.betterem]
[project.markdown_extensions.pymdownx.caret]
[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.emoji]
emoji_generator = "zensical.extensions.emoji.to_svg"
emoji_index = "zensical.extensions.emoji.twemoji"
[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true
[project.markdown_extensions.pymdownx.inlinehilite]
[project.markdown_extensions.pymdownx.keys]
[project.markdown_extensions.pymdownx.magiclink]
[project.markdown_extensions.pymdownx.mark]
[project.markdown_extensions.pymdownx.smartsymbols]
[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }
]
[project.markdown_extensions.pymdownx.tabbed]
alternate_style = true
combine_header_slug = true
[project.markdown_extensions.pymdownx.tasklist]
custom_checkbox = true
[project.markdown_extensions.pymdownx.tilde]

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

Compatibility

The default set of extensions activated by Zensical is different from MkDocs, which only activates meta, toc, tables, and fenced_code from Python Markdown itself. If you experience problems building your project, turn off the defaults, as shown below.

Presets are on the roadmap

We are working on a preset mechanism that simplifies configuration and will allow you to add extensions to a set of defaults, customize extensions included in the defaults, as well as remove them.

Disable the defaults

If you want to reset the behavior to the default behavior of MkDocs, create a configuration with an empty list of extensions:

[project]
markdown_extensions = {}

markdown_extensions: {}