mdformat-hugo

Mdformat plugin for Hugo-flavored Markdown. Formats Hugo content files while preserving shortcodes and markdown attributes.

Features

This plugin adds support for Hugo-specific markdown syntax:

Shortcode Formatting

Hugo shortcodes are formatted with normalized whitespace.

Input:

{{<  ref   "documentation.md"  >}}
{{%   note   %}}

Output:

{{< ref "documentation.md" >}}
{{% note %}}

Both {{< >}} (no markdown processing) and {{% %}} (markdown processed) shortcode styles are supported.

Markdown Attributes

Hugo extends standard Markdown with markdown attributes -- a syntax for attaching HTML attributes (IDs, classes, and key-value pairs) to rendered elements. Attributes are written in curly braces after the element they modify, e.g., {#my-id .my-class key=value}.

This plugin normalizes attribute order and formatting:

1. IDs (#id) come first
2. Classes (.class) follow, sorted alphabetically
3. Key-value pairs (key=value) come last, sorted alphabetically by key
4. Values containing spaces or = are quoted: key="hello world"; otherwise unquoted: key=value

Headings:

## Introduction {.zebra .apple #intro}

Formats to:

## Introduction {#intro .apple .zebra}

Images:

![Logo](logo.png){width=300 .img-fluid height=200}

Formats to:

![Logo](logo.png){.img-fluid height=200 width=300}

Code blocks:

```python {linenos=table .highlight #code}
def hello():
    print("world")
```

Formats to:

```python {#code .highlight linenos=table}
def hello():
    print("world")
```

Additional Features

This plugin bundles support for Hugo markdown features and code block formatting via dependencies:

Markdown syntax:

• mdformat-gfm - GFM tables, strikethrough, task lists, autolinks
• mdformat-front-matters - TOML/YAML/JSON frontmatter
• mdformat-gfm-alerts - Blockquote alerts ([!NOTE], [!WARNING]), [!NOTE] Title)
• mdformat-footnote - Pandoc-style footnotes
• mdformat-deflist - Definition lists

Code block formatting:

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

Usage

mdformat content/