Skip to content

Creating Quills

A Quill is a format bundle that defines how your Markdown content is rendered. This tutorial walks from an empty directory to a rendered PDF.

1. Create the directory

Start with this layout:

my-quill/
├── Quill.yaml
└── plate.typ

2. Write Quill.yaml

Create a minimal but complete config:

quill:
  name: my_quill
  backend: typst
  version: "1.0.0"
  description: A simple letter format
  plate_file: plate.typ

main:
  fields:
    sender:
      type: string
      description: Name of the sender
    recipient:
      type: string
      description: Name of the recipient
    date:
      type: datetime   # accepts bare YYYY-MM-DD as well as full ISO 8601
      description: Letter date

name, backend, version, and description are all required. name must be snake_case. Define your document's expected root-block fields under main.fields. Each field has a type, optional default, description, and validation constraints. Use integer for whole numbers only and number for values that may include decimals. For the full list of field types, UI hints, typed arrays, and enum constraints, see the Quill.yaml Reference.

Use default for the value most authors will accept as-is (the field becomes optional, filled in when omitted). Use example to document the expected shape without supplying a default. Fields with neither are flagged in the blueprint with a <must-fill> sentinel. See the Quill.yaml Reference for details.

3. Write plate.typ

Your first plate template:

#import "@local/quillmark-helper:0.1.0": data

#set page(margin: 1in)

Dear #data.recipient,

#data.at("$body", default: "")

Sincerely,

#data.sender

For data access patterns, helper package details, optional fields, and $cards iteration, see the Typst Backend guide.

4. Write a document

Create a document.md that matches the fields you defined:

~~~
$quill: my_quill
$kind: main
sender: Jane Doe
recipient: John Smith
date: 2026-01-15
~~~

Thank you for your time.

5. Render it

From the same directory, render the document:

quillmark render ./my-quill document.md

For command options and output controls, see the CLI Reference.

6. Next steps

Tip: To exclude files (fonts, build artifacts) from the bundle when loading from disk, add a .quillignore file at the bundle root using gitignore syntax.