Examples

Before-and-after examples of Yamark’s YAML, Markdown, and embedded formatting.

Each example shows a focused input and the output Yamark writes. The site build generates every result with the current Yamark binary.

YAML and Markdown documents

Markdown with YAML front matter

Agent skills and prompt files can put structured metadata above free-form Markdown. Yamark formats both in one pass.

Before

---
name: review-pr
description: Review a pull request and recommend changes inline with the project's style guide, focusing on correctness, readability, and tests.
tags: [review,pull-request,code]
---

#   Review ##

Read the diff and flag anything that violates the style guide, has obvious correctness issues, or looks untested. Prefer specific suggestions over vague concerns.

After

---
name: review-pr
description: >-
  Review a pull request and recommend changes inline with the project's
  style guide, focusing on correctness, readability, and tests.
tags: [review, pull-request, code]
---

# Review

Read the diff and flag anything that violates the style guide, has
obvious correctness issues, or looks untested. Prefer specific
suggestions over vague concerns.

Markdown in YAML

Yamark can format Markdown stored in YAML in three ways: tag the value with !markdown, use !md as a shorter alias, or put # fmt: markdown on the line before the value. The example below shows the full tag and comment forms.

A prompts.yaml or agents.yaml file can use any of these forms. Yamark wraps the selected value as Markdown, choosing folded or literal block style from the content.

Before

agents:
  reviewer:
    instructions: !markdown "Focus on correctness and tests. Flag any change that lacks a regression test. Prefer concrete suggestions: name the function, name the case."
  summarizer:
    # fmt: markdown
    instructions: |
      You write release notes.

      - One bullet per user-visible change.
      - No internal refactors.

After

agents:
  reviewer:
    instructions: !markdown |
      Focus on correctness and tests. Flag any change that lacks a regression
      test. Prefer concrete suggestions: name the function, name the case.
  summarizer:
    # fmt: markdown
    instructions: |
      You write release notes.

      - One bullet per user-visible change.
      - No internal refactors.

The tagged value contains only prose, so Yamark rewraps it as a folded block. The comment-marked value contains a list, so Yamark keeps literal block style (|) because folding would destroy the line breaks Markdown depends on.

Source code in YAML

YAML values can also contain source code. Use # fmt: python, # fmt: r, or the name of another configured formatter before a literal block. When the formatter is available, Yamark formats the block and restores its indentation in the YAML file.

Before

# fmt: python
preflight: |
  def check(items):return all(x>0 for x in items)

After

# fmt: python
preflight: |
  def check(items):
    return all(x > 0 for x in items)

YAML scalar presentation

Yamark changes scalar spelling only when the parsed YAML value and tag stay equivalent. It can simplify safe quoted strings, keep strings that would be misread as booleans, convert hard newlines to literal blocks, and fold long prose strings.

Before

title: "hello"
boolish: "true"
body: "alpha\nbeta\n"
summary: "This package formats YAML front matter and configuration files while preserving semantics, comments, and repository-friendly diffs."

After

title: hello
boolish: "true"
body: |
  alpha
  beta
summary: >-
  This package formats YAML front matter and configuration files while
  preserving semantics, comments, and repository-friendly diffs.

Markdown links, footnotes, and tables

Long inline links are split at Markdown syntax boundaries. Footnote definitions wrap under the marker unless the document or CLI asks to preserve them.

Before

Please be mindful of our [code of conduct](https://github.com/quarto-dev/quarto-cli/blob/main/.github/CODE_OF_CONDUCT.md) as you interact with other community members.

Body text with a footnote.[^long]

[^long]: This footnote explains that comments were removed because people used comments to hold parsing directives and enough extra words to wrap.

After

Please be mindful of our [code of conduct](
  https://github.com/quarto-dev/quarto-cli/blob/main/.github/CODE_OF_CONDUCT.md
) as you interact with other community members.

Body text with a footnote.[^long]

[^long]: This footnote explains that comments were removed because
  people used comments to hold parsing directives and enough extra words
  to wrap.

Simple GFM pipe tables are aligned by display width. Git clean/smudge filters always use compact pipe-table output.

Before

| package | label |
|---|---|
| dplyr | tidy |
| tidyr | pivoting |

After

| package | label    |
| ------- | -------- |
| dplyr   | tidy     |
| tidyr   | pivoting |

Markdown in source files

Hashpipe YAML in source files

Consecutive own-line #| comments in Python and R are a YAML block. Yamark formats the comment body as YAML, restores the hashpipe prefix, and leaves the surrounding source code unchanged. This recognition is automatic; it does not need a fmt: directive.

Before

#| name: demo
#| launcher:
#|  vanilla: true
#|  default-packages: [base,utils]

main <- function() NULL

After

#| name: demo
#| launcher:
#|   vanilla: true
#|   default-packages: [base, utils]

main <- function() NULL

Embedded Markdown in Python

When a prompt lives next to the code that uses it, Yamark can format the prose without changing the surrounding Python. Add # fmt: markdown before the string:

Before

# fmt: markdown
REVIEW_PROMPT = """
# Review

Read the diff and flag anything that violates the style guide, has obvious correctness issues, or looks untested.

-   Prefer specific suggestions over vague concerns.
-   Name the function and the case.
"""

After

# fmt: markdown
REVIEW_PROMPT = """
# Review

Read the diff and flag anything that violates the style guide, has
obvious correctness issues, or looks untested.

- Prefer specific suggestions over vague concerns.
- Name the function and the case.
"""

Python source outside the marked string is left untouched. Run ruff format for that.

Embedded Markdown in source comments

The same directive can target a contiguous source comment block. This is useful for generated help text or documentation snippets where a string literal is not the right host.

Before

# fmt: markdown
# #   Filters
#
# Apply one or more filters. Put the most specific filter first.
#
# -   Each filter is a single expression.

After

# fmt: markdown
# # Filters
#
# Apply one or more filters. Put the most specific filter first.
#
# - Each filter is a single expression.

Embedded Markdown in R

The same pattern works for R raw strings. It can format package vignettes, documentation fragments, and Shiny help text kept next to the code that renders it.

Before

# fmt: markdown
help_text <- r"(
# Filters

Apply one or more filters. Filters are evaluated top-to-bottom; the first match wins, so put the most specific filter first.

-   Each filter is a single expression.
-   Multiple filters combine with AND.
)"

After

# fmt: markdown
help_text <- r"(
# Filters

Apply one or more filters. Filters are evaluated top-to-bottom; the
first match wins, so put the most specific filter first.

- Each filter is a single expression.
- Multiple filters combine with AND.
)"

YAML layout

JSON Lines as a YAML stream

Give a JSON Lines file containing two or more object records a .yaml or .yml extension, with one record per line, then format it normally. Yamark inserts a leading --- document-start marker before every record, including the first, producing a valid YAML multi-document stream. The example below uses records from agent runs.

Before

{"id":1,"profile":{"name":"planner","active":true}}
{"id":2,"profile":{"name":"researcher","active":true},"usage":{"input_tokens":640,"output_tokens":128}}
{"id":3,"profile":{"name":"reviewer","active":true,"model":"gpt-5","region":"us","tools":["search","python"]},"events":[{"type":"tool_call","tools":["search","open","python","write"]},{"type":"usage","tokens":{"input":900,"output":240}},{"type":"completion","status":"ok"}]}

After

---
{id: 1, profile: {name: planner, active: true}}
---
id: 2
profile: {name: researcher, active: true}
usage: {input_tokens: 640, output_tokens: 128}
---
id: 3
profile:
  name: reviewer
  active: true
  model: gpt-5
  region: us
  tools: [search, python]
events:
  - {type: tool_call, tools: [search, open, python, write]}
  - {type: usage, tokens: {input: 900, output: 240}}
  - {type: completion, status: ok}

Yamark keeps each document as compact as the width allows. The first record stays in flow style; the second expands only its root mapping; the third also expands profile and events. Smaller mappings and sequences remain in flow style whenever they still fit within --line-width. This conversion is for object records, not arbitrary JSON values.

Aligned flow-mapping tables

A sequence of similar flow mappings can be easier to scan as a table. Mark it with # fmt: table and Yamark aligns columns by key:

Before

# fmt: table
- {name: alpha,type: string,default: [one,two],description: "Short"}
- {name: beta,type: int,default: 0,description: "Number"}

After

# fmt: table
- {name: alpha, type: string, default: [one, two], description: Short}
- {name: beta,  type: int,    default: 0,          description: Number}

Compact collections

Short, simple block collections can read better as a single flow line. Enable compact = true in yamark.toml (or pass --compact) and Yamark collapses eligible block mappings and sequences that fit the structural width:

Before

tags:
  - yaml
  - markdown
  - docs
package:
  name: yamark
  language: rust

After

tags: [yaml, markdown, docs]
package: {name: yamark, language: rust}

Collections with comments, aliases, tags, anchors, multiline scalars, or block scalars stay in block style.

Collapse to flow by typing a bracket

Drop an unmatched [ or { where a block sequence or mapping value starts and Yamark reads it as a layout hint: collapse this collection onto one line. The file doesn’t parse as you typed it, but the intent is obvious - Yamark removes the opener and emits flow style.

Before

tags: [
  - yaml
  - markdown
  - docs

After

tags: [yaml, markdown, docs]

The opener may also be detached onto the next line after an empty mapping value header:

Before

tags:
[
  - yaml
  - markdown
  - docs

After

tags: [yaml, markdown, docs]

Adjacent forms such as tags:[ and tags:{ are not repaired as layout hints.

A newline inside an existing flow collection requests the reverse change: expand the collection to block style.

Before

- {a: b,
   c: d}

After

- a: b
  c: d

See Supported files and syntax -> Layout repair for the acceptance rules.

Fenced and nested content

Recursive Markdown code fences

YAML fences are formatted as YAML. Markdown fences are formatted recursively, so nested YAML inside nested Markdown is formatted too.

Before

```yaml
# fmt: table
- {name: a,type: int,default: 0}
- {name: long_name,type: string,default: ""}
```

````markdown
#   Inner

```yaml
items: [a,b]
```
````

After

```yaml
# fmt: table
- {name: a,         type: int,    default: 0}
- {name: long_name, type: string, default: ""}
```

````markdown
# Inner

```yaml
items: [a, b]
```
````

Prettier-backed web and data fences

When prettier is on PATH, JSON, JSONC, JSON5, GraphQL, CSS, SCSS, Less, PostCSS, HTML, JavaScript, JSX, TypeScript, and TSX fenced blocks are handed to it. Python and R fences go to Ruff and Air the same way:

Before

```json
{"name":"yamark","tags":["yaml","markdown","formatter"],"engines":{"node":">=18"}}
```

```ts
function format(input:string):string{return input.trim()}
```

After

```json
{
  "name": "yamark",
  "tags": ["yaml", "markdown", "formatter"],
  "engines": { "node": ">=18" }
}
```

```ts
function format(input: string): string {
  return input.trim();
}
```

A missing prettier leaves the fence unchanged. Override or disable a language with [embedded.<language>] in yamark.toml, or skip them all with --skip-embedded-formatters.

---

Once an example has shown you the behavior, see Directives for how to place those instructions in Markdown, YAML, Python, and R files. Use Reference to look up exact directive grammar, formatting settings, supported syntax, and failure behavior.