Yamark

Yamark is a fast formatter for YAML and Markdown. It formats whole files and embedded content, keeping source readable and changes easy to review. Regions without a supported rewrite stay unchanged.

For supported embedded code, Yamark can also call Ruff, Air, Prettier, or another configured formatter.

See the documentation for examples, configuration, editor integrations, and the full syntax reference.

Install

With uv installed, run Yamark directly from PyPI without a separate install:

uvx yamark format config.yaml docs/

This formats the selected files in place. To install a persistent yamark command:

uv tool install yamark

Usage

The examples below use an installed yamark command. To keep running from PyPI without installing it, replace yamark with uvx yamark.

Format one or more files or directories in place:

yamark format config.yaml docs/

Format the current directory:

yamark format

Check whether files are already formatted without writing changes:

yamark format --check docs/

Show a unified diff without writing changes:

yamark format --diff docs/

Format stdin for editor and CI integrations:

yamark format --stdin-file-path config.yaml < config.yaml

Convert JSON-family input from stdin to formatted YAML on stdout:

yamark to-yaml --stdin-file-path data.json5 < data.json5

The path is not read or written. Its suffix selects the exact JSON dialect. This is a conversion, not source formatting.

Directory traversal skips hidden paths and respects .gitignore, .ignore, and global Git ignore files by default. Pass a hidden path explicitly to format it.

While formatting is enabled, standalone {{< ... >}} and {{% ... %}} shortcode tokens are preserved, including multiline tokens and quoted arguments. Directive-looking text inside a recognized token is data. Yamark does not match shortcode names or interpret their bodies: Markdown between tokens formats normally. An unterminated token or quote preserves the rest of the enclosing Markdown document or fragment. This does not guarantee rendering equivalence for arbitrary Hugo or Jinja templates.

To disable body formatting, surround the region with <!-- fmt: off --> and <!-- fmt: on -->. While formatting is disabled, directives follow the existing linewise policy: a recognized fmt: on line resumes formatting even if the surrounding text resembles a shortcode argument, code fence, HTML, or math block.

Explicitly skipped Markdown retains its bytes, including trailing spaces and line endings: <!-- fmt: skip --> preserves the next selected node, <!-- fmt: off --> preserves the disabled region, and <!-- fmt: skip file --> preserves the enclosing Markdown document or fragment. This protection survives supported nesting in Markdown fences and divs; surrounding Markdown still formats.

Editor integrations

The VS Code and Positron formatter extension lives in editors/vscode/. See the editor guide for installation and configuration.

Development

Building from source requires Rust 1.98.1 or newer.

Build or install the binary from a checkout:

cargo build --bin yamark
cargo install --path .

Build a Python wheel for local testing:

uvx maturin build --release

Run the Rust tests, formatting check, and lints:

cargo test
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Run the external CLI and VS Code extension tests separately:

uv run external-tests/run.py
cd editors/vscode
npm test

When tests/yaml-test-suite/data exists, cargo test also runs the YAML Test Suite round-trip test. Populate that directory with:

tools/bootstrap-yaml-test-suite-data.py --source ~/github/posit-dev/r-yaml12/tests/testthat/yaml-test-suite

Use the pages linked from website/reference.qmd and the public CLI tests as behavior references.

Release

See the release guide for the stable-version bump, checks, release notes, tag, publication verification, and post-release +dev bump.