Metadata-Version: 2.4
Name: mdformat-zola
Version: 1.0.0
Summary: Mdformat plugin for Zola-flavored Markdown
Project-URL: Documentation, https://github.com/gaborbernat/mdformat-zola
Project-URL: Homepage, https://github.com/gaborbernat/mdformat-zola
Project-URL: Source, https://github.com/gaborbernat/mdformat-zola
Project-URL: Tracker, https://github.com/gaborbernat/mdformat-zola/issues
Maintainer-email: Bernát Gábor <gaborjbernat@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Bernát Gábor
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: formatter,markdown,mdformat,zola
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: markdown-it-py>=4.2
Requires-Dist: mdformat-config>=0.2.1
Requires-Dist: mdformat-deflist>=0.1.4
Requires-Dist: mdformat-footnote>=0.1.3
Requires-Dist: mdformat-front-matters>=2
Requires-Dist: mdformat-gfm-alerts>=2
Requires-Dist: mdformat-gfm>=1
Requires-Dist: mdformat-pyproject>=0.1.1
Requires-Dist: mdformat-ruff>=0.1.3
Requires-Dist: mdformat-shfmt>=0.2
Requires-Dist: mdformat-web>=0.2
Requires-Dist: mdformat>=1
Requires-Dist: mdit-py-plugins>=0.6.1
Description-Content-Type: text/markdown

# mdformat-zola

[![PyPI](https://img.shields.io/pypi/v/mdformat-zola?style=flat-square)](https://pypi.org/project/mdformat-zola/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/mdformat-zola.svg)](https://pypi.org/project/mdformat-zola/)
[![check](https://github.com/gaborbernat/mdformat-zola/actions/workflows/check.yaml/badge.svg)](https://github.com/gaborbernat/mdformat-zola/actions/workflows/check.yaml)

Mdformat plugin for [Zola](https://www.getzola.org)-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:**

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

**Output:**

```markdown
{{ 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:

```markdown
{% 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`:

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

```toml
# .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](https://www.getzola.org/documentation/content/linking/) with a
`{#id .class}` suffix. The plugin puts the id first, then the classes in alphabetical order:

```markdown
## Introduction {.lead #intro}
```

Formats to:

```markdown
## Introduction {#intro .lead}
```

### Code-block annotations

The plugin reorders Zola's
[syntax-highlighting annotations](https://www.getzola.org/documentation/content/syntax-highlighting/) to a fixed
sequence (`linenos`, `linenostart`, `hl_lines`, `hide_lines`, `name`), normalizes their whitespace, and keeps unknown
annotations:

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

Formats to:

````markdown
```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](https://github.com/hukkin/mdformat-gfm) - tables, strikethrough, task lists, autolinks
- [mdformat-front-matters](https://github.com/kyleking/mdformat-front-matters) - TOML/YAML/JSON frontmatter
- [mdformat-gfm-alerts](https://github.com/KyleKing/mdformat-gfm-alerts) - blockquote alerts (`[!NOTE]`, `[!WARNING]`)
- [mdformat-footnote](https://github.com/executablebooks/mdformat-footnote) - footnotes
- [mdformat-deflist](https://github.com/executablebooks/mdformat-deflist) - definition lists

**Code-block formatting:**

- [mdformat-ruff](https://github.com/Freed-Wu/mdformat-ruff) - Python blocks with ruff
- [mdformat-shfmt](https://github.com/hukkin/mdformat-shfmt) - shell blocks with shfmt
- [mdformat-config](https://github.com/hukkin/mdformat-config) - JSON, YAML, TOML blocks
- [mdformat-web](https://github.com/hukkin/mdformat-web) - HTML, CSS, JavaScript blocks
- [mdformat-pyproject](https://github.com/csala/mdformat-pyproject) - pyproject.toml blocks

## Usage

```bash
mdformat content/
```
