mdformat-zola

Mdformat plugin for Zola-flavored Markdown. It formats Zola content files while keeping shortcodes, heading anchors, and code-block annotations intact.

Plain mdformat mangles Zola content. It reflows shortcode bodies (a Mermaid diagram becomes one escaped line), escapes the * in {{/* … */}}, and wraps long inline shortcodes mid-call. This plugin adds Zola's syntax to mdformat so those constructs round-trip.

Zola syntax

Each construct below gets one stable form. Where Zola treats ordering as insignificant, the plugin sorts.

Shortcodes

The plugin normalizes inline shortcodes {{ name(args) }} and their escaped form {{/* name(args) */}}: it collapses whitespace, sorts arguments by name, and settles on one quote style. It does not wrap or escape them.

Input:

{{  youtube( autoplay=true ,  id="dQw4w9WgXcQ" ) }}

Output:

{{ youtube(autoplay=true, id="dQw4w9WgXcQ") }}

Body shortcodes {% name(args) %} … {% end %} (and the escaped {%/* … */%}) get the same treatment on their opening tag. A raw body such as a Mermaid diagram stays byte-for-byte:

{% mermaid() %}
graph TD
  A["velodex[x]"] --> B[*]
{% end %}

The body of a prose shortcode is Markdown that Zola re-renders, so the plugin formats it. By default this applies to admonition, aside, callout, caution, details, important, note, quote, tip, and warning; every other shortcode keeps its body verbatim. Point the plugin at your own set with the markdown_shortcodes option, on the CLI or in .mdformat.toml:

mdformat --zola-markdown-shortcodes quote,note,sidebar content/

# .mdformat.toml
[plugin.zola]
markdown_shortcodes = ["quote", "note", "sidebar"]

Pass an empty value to keep every body verbatim.

Heading anchors

Zola lets you pin a heading's id and classes with a {#id .class} suffix. The plugin puts the id first, then the classes in alphabetical order:

## Introduction {.lead #intro}

Formats to:

## Introduction {#intro .lead}

Code-block annotations

The plugin reorders Zola's syntax-highlighting annotations to a fixed sequence (linenos, linenostart, hl_lines, hide_lines, name), normalizes their whitespace, and keeps unknown annotations:

```rust, hl_lines=3-4  8-9,linenos , linenostart=10

Formats to:

```rust,linenos,linenostart=10,hl_lines=3-4 8-9

Internal links such as [text](@/pages/about.md#anchor) survive as ordinary links, no special handling needed.

Bundled features

Installing the plugin pulls in the mdformat plugins that cover the rest of Zola's Markdown flavor (GitHub-Flavored Markdown with footnotes, definition lists, alerts, and TOML +++ frontmatter), plus code formatters for fenced blocks:

Markdown syntax:

• mdformat-gfm - tables, strikethrough, task lists, autolinks
• mdformat-front-matters - TOML/YAML/JSON frontmatter
• mdformat-gfm-alerts - blockquote alerts ([!NOTE], [!WARNING])
• mdformat-footnote - footnotes
• mdformat-deflist - definition lists

Code-block formatting:

• mdformat-ruff - Python blocks with ruff
• mdformat-shfmt - shell blocks with shfmt
• mdformat-config - JSON, YAML, TOML blocks
• mdformat-web - HTML, CSS, JavaScript blocks
• mdformat-pyproject - pyproject.toml blocks

Usage

mdformat content/