# Python Markdown

Zensical supports a large number of [Python Markdown](<https://python-markdown.github.io/>) extensions, which is part of what makes it so attractive for technical writing. Following is a list of all supported extensions, linking to the relevant sections of the authoring guide for which features they need to be enabled.

## Supported extensions

### Abbreviations

The [Abbreviations](<https://python-markdown.github.io/extensions/abbreviations/>) extension adds the ability to add a small tooltip to an element, by wrapping it with an `abbr` tag. Only plain text (no markup) is supported. Enable it via:

```toml
[project.markdown_extensions]
abbr = {}
```

```yaml
markdown_extensions:
  - abbr
```

No configuration options are available. See the following authoring guides for usage:

- [Adding abbreviations](<https://zensical.org/docs/authoring/tooltips/#add-abbreviations>)
- [Adding a glossary](<https://zensical.org/docs/authoring/tooltips/#add-a-glossary>)

### Admonition

The [Admonition](<https://python-markdown.github.io/extensions/admonition/>) extension adds support for admonitions, more commonly known as *call-outs*, which can be defined in Markdown by using a simple syntax. Enable it via:

```toml
[project.markdown_extensions]
admonition = {}
```

```yaml
markdown_extensions:
  - admonition
```

No configuration options are available. See the following authoring guides for usage:

- [Adding admonitions](<https://zensical.org/docs/authoring/admonitions/#usage>)
- [Changing the title](<https://zensical.org/docs/authoring/admonitions/#change-the-title>)
- [Removing the title](<https://zensical.org/docs/authoring/admonitions/#remove-the-title>)
- [Supported types](<https://zensical.org/docs/authoring/admonitions/#supported-types>)

### Attribute Lists

The [Attribute Lists](<https://python-markdown.github.io/extensions/attr_list/>) extension allows to add HTML attributes and CSS classes to [almost every](<https://python-markdown.github.io/extensions/attr_list/#limitations>) Markdown inline- and block-level element with a special syntax. Enable it via:

```toml
[project.markdown_extensions]
attr_list = {}
```

```yaml
markdown_extensions:
  - attr_list
```

No configuration options are available. See the following authoring guides for usage:

- [Using grids](<https://zensical.org/docs/authoring/grids/#usage>)
- [Adding buttons](<https://zensical.org/docs/authoring/buttons/#add-a-button>)
- [Adding tooltips](<https://zensical.org/docs/authoring/tooltips/#add-a-tooltip>)
- [Using icons with colors](<https://zensical.org/docs/authoring/icons-emojis/#with-colors>)
- [Using icons with animations](<https://zensical.org/docs/authoring/icons-emojis/#with-animations>)
- [Image alignment](<https://zensical.org/docs/authoring/images/#image-alignment>)
- [Image lazy-loading](<https://zensical.org/docs/authoring/images/#image-lazy-loading>)

### Definition Lists

The [Definition Lists](<https://python-markdown.github.io/extensions/definition_lists/>) extension adds the ability to add definition lists (more commonly known as [description lists](<https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl>) – `dl` in HTML) via Markdown to a document. Enable it via:

```toml
[project.markdown_extensions]
def_list = {}
```

```yaml
markdown_extensions:
  - def_list
```

No configuration options are available. See the following authoring guides for usage:

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

### Footnotes

The [Footnotes](<https://python-markdown.github.io/extensions/footnotes/>) extension allows to define inline footnotes, which are then rendered below all Markdown content of a document. Enable it via:

```toml
[project.markdown_extensions]
footnotes = {}
```

```yaml
markdown_extensions:
  - footnotes
```

No configuration options are supported. See the following authoring guides for usage:

- [Adding footnote references](<https://zensical.org/docs/authoring/footnotes/#adding-footnote-references>)
- [Adding footnote content](<https://zensical.org/docs/authoring/footnotes/#add-footnote-content>)

### Markdown in HTML

The [Markdown in HTML](<https://python-markdown.github.io/extensions/md_in_html/>) extension allows for writing Markdown inside of HTML, which is useful for wrapping Markdown content with custom elements. Enable it via:

```toml
[project.markdown_extensions]
md_in_html = {}
```

```yaml
markdown_extensions:
  - md_in_html
```

> By default, Markdown ignores any content within a raw HTML block-level element. With the `md_in_html` extension enabled, the content of a raw HTML block-level element can be parsed as Markdown by including a `markdown` attribute on the opening tag. The `markdown` attribute will be stripped from the output, while all other attributes will be preserved.

No configuration options are available. See these examples for how `md_in_html` can be used:

- [Using grids](<https://zensical.org/docs/authoring/grids/#usage>)
- [Image captions](<https://zensical.org/docs/authoring/images/#image-captions>)

### Table of Contents

The [Table of Contents](<https://python-markdown.github.io/extensions/toc/>) extension automatically generates a table of contents from a document, which Zensical will render as part of the resulting page. Enable it via:

```toml
[project.markdown_extensions]
toc.permalink = true
```

```yaml
markdown_extensions:
  - toc:
      permalink: true
```

The following configuration options are supported:

#### `toc.title`

This option sets the title of the table of contents in the right navigation sidebar, which is normally automatically sourced from the translations for the [site language](<https://zensical.org/docs/setup/language/#site-language>). Set the title explicitly via:

```toml
[project.markdown_extensions]
toc.title = "On this page"
```

```yaml
markdown_extensions:
  - toc:
      title: On this page
```

#### `toc.permalink`

This option adds an anchor link containing the paragraph symbol `¶` or another custom symbol at the end of each headline, exactly like on the page you're currently viewing. The symbol is hidden by default to keep the page free from clutter but Zensical will make it appear on hover.

If you do not like the default symbol `¶`, you can configure another symbol or string like so:

```toml
[project.markdown_extensions]
toc.permalink = "⚓︎"
```

```yaml
markdown_extensions:
  - toc:
      permalink: ⚓︎
```

#### `toc.permalink_title`

This option sets the title of the anchor link which is shown on hover and read by screen readers. For accessibility reasons, it might be beneficial to change it to a more discernable name, stating that the anchor links to the section itself:

```toml
[project.markdown_extensions]
toc.permalink_title = "Anchor link to this section"
```

```yaml
markdown_extensions:
  - toc:
      permalink_title: Anchor link to this section
```

#### `toc.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/>):

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

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

#### `toc.toc_depth`

Define the range of levels to be included in the table of contents (default: 6). This may be useful for project documentation with deeply structured headings to decrease the length of the table of contents:

```toml
[project.markdown_extensions]
toc.toc_depth = 3
```

```yaml
markdown_extensions:
  - toc:
      toc_depth: 3
```

To remove the table of contents altogether:

```toml
[project.markdown_extensions]
toc.toc_depth = 0
```

```yaml
markdown_extensions:
  - toc:
      toc_depth: 0
```

> [!NOTE]
>
> **Other options**
>
> 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.

### Tables

The [Tables](<https://python-markdown.github.io/extensions/tables/>) extension adds the ability to create tables in Markdown by using a simple syntax. Enable it via:

```toml
[project.markdown_extensions]
tables = {}
```

```yaml
markdown_extensions:
  - tables
```

No configuration options are available. See the following authoring guides for usage:

- [Using data tables](<https://zensical.org/docs/authoring/data-tables/#usage>)
- [Column alignment](<https://zensical.org/docs/authoring/data-tables/#column-alignment>)