orz-paged — documents & layout

What a .paged.html is

One self-contained HTML file that shows your Markdown as a sequence of real print pages on light paper — page size, margins, running headers/footers, page numbers — using paged.js, in any modern browser. Edit it side by side with a live paged preview, save in place, and export to PDF by printing (Ctrl/Cmd + P → Save as PDF): the pages you see are exactly what prints. It mimics ink on paper — light backgrounds only, no dark mode, and screen-only constructs (tabs, spoilers, video) are discouraged.

orz-paged is published on npm as orz-paged and orz-paged-browser. Use npx orz-paged paper.md, or start from the official blank .paged.html starter.

The quick way: the template picker

In the editor, open the template button (the document icon) and pick a starter. On a blank document it drops the skeleton straight in; on one that already has content it inserts the template and tucks your old content into a comment. There are twelve starters across six kinds:

Everything below is what those starters are made of — reach for it when you want a custom title block, a dedicated cover page, a tailored variant, or your own styling.

Document settings

One {{nyml kind: document}} block at the top configures the whole document. Template-first: most documents set only template: (and maybe theme:); the rest are optional overrides.

{{nyml
kind: document
template: report-page    # picks the layout + a starter skeleton
theme: light-neat-1      # the look (font + accent + element styling)
page_size: Letter        # A3 · A4 · A5 · Letter · Legal · or "210mm 297mm"
margin_top: 20           # margin_top/bottom/left/right, in mm
decoration_color: "#2962a4"   # accent (overrides the theme's)
header_center: Quarterly Report
footer_left: Confidential
page_number_position: footer-right   # header/footer-left|center|right · none
page_number_style: page-n-of-N       # simple · page-n · page-n-of-N · n-of-N · n-slash-N · dash-n-dash · brackets · parentheses
front_matter: clean      # unnumbered title/abstract/toc pages; body restarts at 1
dynamic_choices: |       # the dynamic switch (see below)
  answer-key: hide
}}

Fonts: serif (system-serif, source-serif-4, lora, crimson-pro, noto-serif) · sans (inter, ibm-plex-sans, roboto, raleway, noto-sans) · mono (courier-prime). Set font_preset only to override the theme's font.

Templates & themes

A template owns layout (page size, furniture, which elements appear and where). A theme owns the look (font, accent color, element styling) — so the same theme renders the same across every template. article/report/exam each come in a -page (dedicated title/cover page) and a -section (inline title) variant.

Seven light themes (light only by design): light-neat-1/2/3 (modern sans), light-academic-1/2 (scholarly serif), beige-decent-1/2 (warm editorial). The default is light-academic-1. Switch live from the editor's theme menu, or set theme:.

Document elements

An element is a {{nyml kind: <element>}} block placed where you want it in the body. The curated set:

Authors, affiliations & ORCID

For multi-author papers, use authors (one per line) plus affiliations and notes as key: text lists. Each author line is Name | marks | email | orcid — the fields after the name are auto-detected, so order is flexible and any may be omitted.

{{nyml
kind: article-title
title: A Practical Comparison of RAFT and ATRP
authors: |
  Jane Doe | 1,* | jane.doe@example.edu | 0000-0002-1825-0097
  John Smith | 2
affiliations: |
  1: Department of Chemistry, University of Example
  2: Institute of Science, Example Lab
notes: |
  *: Corresponding author
placement: page
}}

Exam questions

Put student fields and instructions on the exam-title (first page). In answer, list one correct option — or several for select-all (B, D). The answer key is shown only when the switch is on.

{{nyml
kind: exam-title
student_fields: |
  Name | Student ID | Score / 100
instructions: |
  - Answer all questions; show your work for full credit.
}}

{{nyml
kind: question-mc
n: 1
pts: 5 pts
body: Which of these are vector quantities? (Select all that apply.)
options: |
  A. Mass
  B. Velocity
  C. Temperature
  D. Force
answer: B, D
}}

Beyond templates: customizing layout

::: page-break
:::

Dynamic switch — one source, several versions

dynamic_choices is a key: value map that drives conditional content. Tag any element with data-show-when="key=value" or data-hide-when="key=value"; non-matching elements are dropped at render time. The headline use is exam answer keys — question answers are tagged answer-key=show, so one source prints the student copy (answer-key: hide) and the instructor key (show). Flip it in the source, or live from the editor's answer key dropdown. Define your own keys (e.g. audience: student) for any tailored-variant document.

Body content is full orz-markdown

Between the elements, write normal orz-markdown — headings, lists, tables, blockquotes, code, footnotes, math ($E=mc^2$ / $$ … $$), Mermaid diagrams, {{smiles}} chemistry, {{chart}}, {{qr}} (a printed QR is genuinely useful), admonitions (::: info / success / warning / danger), and columns. Everything is styled for print. Avoid screen-only constructs — tabs, ::: spoil, and youtube — they don't print.

Worked examples

Academic article — cover page, abstract, math

{{nyml
kind: document
template: article-page
theme: light-academic-1
front_matter: clean
}}

{{nyml
kind: article-title
title: On Widgets
subtitle: A Study
author: Ada Lovelace
date: March 2026
placement: page
}}

{{nyml
kind: abstract
text: We show that widgets ...
keywords: widgets, gadgets
placement: page
}}

## Introduction
Inline math $E = mc^2$, tables, lists, all print.

Exam — student copy & instructor key from one source

{{nyml
kind: document
template: exam-page
dynamic_choices: |
  answer-key: hide      # ← flip to show for the key
}}

{{nyml
kind: exam-title
title: Physics — Exam 1
student_fields: |
  Name | Student ID | Score / 100
}}

{{nyml
kind: question-mc
n: 1
body: SI unit of force?
options: |
  A. Joule
  B. Newton
answer: B
}}

A modern CV

{{nyml
kind: document
template: cv-modern
}}

{{nyml
kind: cv-header
full_name: Your Name
title: Job Title / Professional Tagline
contacts: |
  you@example.com
  City, Country
}}

## Experience
### Senior Role {{span[cv-date] 2022 – Present}}
Company Name, City
- Led a key initiative with a measurable result.

## Skills
{{span[cv-chip] React}} {{span[cv-chip] TypeScript}} {{span[cv-chip] Design}}

For the full vocabulary — every element field, theme, page-number style, and the print-first guidance — read the agent skill (orz-paged-skills/SKILL.md) or just ask an agent.