Yamark

A fast formatter for YAML and Markdown.

Yamark formats whole files and embedded content with the consistency we expect from code, keeping source readable and changes easy to review.

Install See examples

Run directly from PyPI uvx yamark format

Format

Rewrite supported files in place.

Check

Use non-mutating CI and diff modes.

Embed

Format marked Markdown in YAML, Python, or R.

Recurse

Format nested YAML and Markdown inside fenced blocks.

A quick example

A short Markdown file with YAML front matter - a native document format for LLM work. It combines software-readable structure with natural language for prompts, skills, reference documents, and generated output. The Before pane shows the unformatted source; the After pane shows what yamark format writes back.

Before 

---
title: Why YAML + Markdown?
description: The source languages of LLM work - structured fields for tools alongside instructions, examples, and context for models.
tags: [llm,authoring,formats]
---

#   Why YAML + Markdown? ##

When LLMs become part of a software system, YAML and Markdown start to feel like programming languages. YAML defines named fields tools can act on; Markdown carries the instructions, examples, and context that shape model behavior. Together they create a shared source file that stays readable to people and models, exposes explicit structure to software, produces clear diffs, and renders directly.

Where the combination shines:

- Agent skills and prompt files keep names, versions, and tool metadata beside the instructions they describe.
  - The Markdown body can carry code samples and nested structures with their own syntax and indentation.
- Reference documents stay readable to authors and models without a separate source format or build step.
- Tool inputs and model outputs survive chat, Git, and documentation pipelines as recognizable text.
- One source can render as HTML or PDF and travel unchanged as agent context.

After

---
title: Why YAML + Markdown?
description: >-
  The source languages of LLM work - structured fields for tools alongside
  instructions, examples, and context for models.
tags: [llm, authoring, formats]
---

# Why YAML + Markdown?

When LLMs become part of a software system, YAML and Markdown start to
feel like programming languages. YAML defines named fields tools can act
on; Markdown carries the instructions, examples, and context that shape
model behavior. Together they create a shared source file that stays
readable to people and models, exposes explicit structure to software,
produces clear diffs, and renders directly.

Where the combination shines:

- Agent skills and prompt files keep names, versions, and tool metadata
  beside the instructions they describe.
  - The Markdown body can carry code samples and nested structures with
    their own syntax and indentation.
- Reference documents stay readable to authors and models without a
  separate source format or build step.
- Tool inputs and model outputs survive chat, Git, and documentation
  pipelines as recognizable text.
- One source can render as HTML or PDF and travel unchanged as agent
  context.

Toggle soft wrap on the Before pane to inspect the input’s physical lines. Yamark wraps and indents each region according to its own grammar.

Performance

On the benchmark host (Apple M4 Max, macOS arm64), Yamark recorded the lowest elapsed time in all four workloads: 78–117 ms for each generated 4 MB file and 181 ms for 500 generated YAML files (50 MB).

Elapsed time across formatter CLIs

Every formatter in the checked-in comparison. Median wall time; lower is better. All four panels share a logarithmic seconds scale.

Exact values:

  • 4 MB Markdown - Yamark: 117 ms
  • 4 MB Markdown - dprint: 378 ms
  • 4 MB Markdown - Deno: 412 ms
  • 4 MB Markdown - Panache: 417 ms
  • 4 MB Markdown - Prettier: 1.9 s
  • 4 MB Markdown - mdformat: 3.4 s
  • 4 MB YAML - Yamark: 78 ms
  • 4 MB YAML - yamlfmt: 196 ms
  • 4 MB YAML - Deno: 766 ms
  • 4 MB YAML - dprint: 1.2 s
  • 4 MB YAML - yamlfix: 7.6 s
  • 4 MB YAML - Prettier: 20.6 s (file unchanged)
  • 4 MB Markdown + front matter - Yamark: 111 ms (formatted)
  • 4 MB Markdown + front matter - dprint: 345 ms (untouched)
  • 4 MB Markdown + front matter - Deno: 420 ms (formatted)
  • 4 MB Markdown + front matter - Prettier: 1.9 s (formatted)
  • 4 MB Markdown + front matter - mdformat: 3.8 s (not preserved)
  • 4 MB Markdown + front matter - Panache: 6.5 s (formatted)
  • 500 YAML files · 50 MB - Yamark: 181 ms
  • 500 YAML files · 50 MB - Deno: 2.5 s
  • 500 YAML files · 50 MB - dprint: 3.0 s
  • 500 YAML files · 50 MB - yamlfmt: 4.0 s
  • 500 YAML files · 50 MB - Prettier: 45.0 s
  • 500 YAML files · 50 MB - yamlfix: 176.3 s

The Benchmarks page includes detailed tables, methodology, checked-in results, and reproduction commands.