Usage

Install Yamark, format files, and choose an integration.

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

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

The checkout pins Rust 1.98.1. Building from source requires Rust 1.98.1 or newer. To build from a checkout, run:

cargo install --path .

Format files

Format one or more files or directories in place:

yamark format config.yaml docs/

Format the current directory:

yamark format

By default, Markdown prose wraps at column 72 without forcing sentence boundaries. Override this behavior with --wrap, for example:

yamark format --wrap sentence:88 docs/

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

CI and stdin

Use check, diff, or stdin modes for integrations:

yamark format --check docs/
yamark format --diff docs/
yamark format --stdin-file-path config.yaml < config.yaml

--check and --diff do not write files. Both exit 1 when any selected file would change.

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.

For yamark format, use --diagnostics to explain preserved content. Use --skip-embedded-formatters when another tool formats the same embedded code.

Integrations

  • Examples: focused before-and-after output from the current Yamark binary.
  • Directives: put formatting choices beside content in Markdown, YAML, Python, and R files.
  • Editors: VS Code, Positron, and compatible forks - commands, settings, format-on-save, formatter chaining, and logs.
  • Reference: look up supported files and syntax, formatting settings, yamark.toml, directive grammar, and command behavior.
  • Command line: modes, output, exit status, and generated --help for Yamark, format, to-yaml, and the git-filter command group.
  • Git Filter: an experimental workflow that stores Markdown sentence-per-line while keeping the working tree column-wrapped.