quickstart.md

Quickstart

This walkthrough takes you from an empty folder to a rendered PDF.

1. Write a report

Create a file called report.yml (or, you know, something meaningful to you).

The top-level keys are your headings, and their values are the content (paragraphs or otherwise) underneath them.

See the example below:

Site inspection report:
  - >
    This is the first paragraph. The `>` character tells YAML you are entering a
    multi-line string that should be word-wrapped. Leave a blank line to start a new
    paragraph.
  - Findings:
    - Bullets:
      - The handrail is loose on the north stair.
      - Two ceiling tiles are water-stained in the lobby.
    - Items observed:
      - Item Number: 12.01
        Description: There is a problem here. This report documents it.
        Location: Under the stairs
      - Item Number: 12.02
        Description: Five ladybugs on the table cloth.
        Location: Kitchen

A few things are happening here:

• Site inspection report: is the document heading (an <h1>).
• Each - under it is a list item rendered in document order.
• Findings: is a nested sub-heading, because it is a key whose value is more content.
• Bullets: renders a bulleted list; Items observed: renders a table because each list item is a mapping (the keys become column headers).

See Document structure for the full set of rules.

2. Render it

ym convert report.yml

✍️ .... 📝 ... PDF created: /path/to/report.pdf

By default the PDF is written next to the source file with a .pdf extension. To choose a destination:

ym convert report.yml output/inspection.pdf

The output directory(ies) will be created if the do not already exist.

3. Iterate live (optional)

While drafting, run ym live to open the PDF and rebuild it automatically every time you save:

ym live report.yml

Leave it running in a terminal, edit report.yml in your editor, and the preview refreshes on save. Press Ctrl+C to stop (which will also close the attached Okular instance).

4. Style it

Add configuration keys prefixed with an underscore at the top of the file. For example, to change the body font and heading colour:

_style:
  body:
    font: NotoSans
  headings:
    font: AppleGaramond
    color: "#dd9922"

Site inspection report:
  - >
    Everything below inherits the styles above.

Configuration can live inline (as above) or in a shared project config file so several documents look alike. See Configuration.

5. Add richer content

When plain prose isn't enough, reach for a block — a key that starts with an underscore and expands into custom content:

Report:
  - Photos:
    _img:
      src: site.png
      caption: "Figure 1: The north stairwell"
      scale_ratio: 0.5
  - _info: Remember to file this report by end of week.
  - _pagebreak:

The full catalogue is in the Blocks reference.

Where to go next

• Document structure — the mental model for YAML → PDF.
• Blocks reference — every built-in block and its parameters.
• Configuration — page templates, text styles, table styles.
• Variables — _vars, Jinja interpolation, and $var passing.
• CLI reference — ym convert and ym live in detail.