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.

To build from a checkout, install Rust 1.88 or newer and 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.