About extensions¶

Markdown is a very small language with an initial implementation by John Gruber that has long served as the reference for Markdown implementations. Its minimal functionality makes it easy to learn but also limits what it can express. Zensical currently uses Python Markdown, which supports additional syntax elements provided by Markdown extensions. These enrich Python Markdown and make it suitable for technical writing.

Zensical extensions¶

Zensical itself provides support for a number of extensions in addition to the Python Markdown extensions described below.

• GLightbox
• Macros
• mkdocstrings

Python Markdown Extensions¶

Since Zensical currently uses Python Markdown, its extensions for the original Markdown syntax are available. The Python Markdown Extensions package is also installed with Zensical, adding more extensions.

Most of the extensions are enabled by default and are included explicitly in the template generated by the zensical new command. You can turn off the defaults if they do not suit your project.

The following extensions are all supported by Zensical and therefore strongly recommended. Click on each extension to learn about its purpose and 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

Turning off 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: {}