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¶

Because Zensical uses Python Markdown, its built-in extensions are available. Zensical also installs the Python Markdown Extensions package, which provides additional extensions. Most are enabled by default and listed explicitly in the zensical.toml file generated by zensical new.

The following extensions are 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 default configuration is written to the generated zensical.toml file:

[project.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_generator = "zensical.extensions.emoji.to_svg"
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji"
pymdownx.highlight.anchor_linenums = true
pymdownx.highlight.line_spans = "__span"
pymdownx.highlight.pygments_lang_class = true
pymdownx.inlinehilite = {}
pymdownx.keys = {}
pymdownx.magiclink = {}
pymdownx.mark = {}
pymdownx.smartsymbols = {}
pymdownx.superfences.custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
]
pymdownx.tabbed.alternate_style = true
pymdownx.tabbed.combine_header_slug = true
pymdownx.tasklist.custom_checkbox = true
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_generator: !!python/name:zensical.extensions.emoji.to_svg
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
  - 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