A data-driven Chinese poetry reader for Typst. It provides A4/A5/A6 page profiles, one- or two-column layouts, pinyin ruby annotations, short notes under each poem, chapter covers, a table of contents, and optional appendix pages for poet biographies, famous lines, and an author index.

The package contains the layout engine and a small public-domain example. It does not bundle a poetry corpus, curriculum, school logo, or other institution-specific data. You provide the content as a Typst dictionary or a JSON file.

Quick start

Create a project from the template:

typst init @preview/shiyin-reader:0.1.0 my-poetry-book
cd my-poetry-book
typst compile main.typ

Or import the package directly:

#import "@preview/shiyin-reader:0.1.0": poem-book
#let book = json("book.json")
#show: poem-book.with(book: book)

Data model

Book dictionary

metadata

format

notes

notes: (mode: "short")

"short" renders numbered notes under each poem. Other values render no notes; footnote rendering is not implemented yet.

branding

All fields are optional. The cover and back cover hide empty branding blocks automatically.

features

front-matter

front-matter: (
  title: "卷首语",
  preface: "Plain-text preface.",
  paragraphs: (
    "First paragraph.",
    "Second paragraph.",
  ),
)

paragraphs is what gets rendered. preface is optional metadata kept for convenience.

appendix

appendix: (
  famous-lines: (
    (quote: "春眠不觉晓，处处闻啼鸟。", source: "孟浩然《春晓》"),
  ),
  poet-heading: "【诗人简介】",
  poets: (
    (group: "唐", name: "孟浩然", years: "689—740", bio: "唐代诗人，襄阳人。"),
  ),
  author-index: (
    (
      initial: "M",
      name: "孟浩然",
      dynasty: "唐",
      poems: ((title: "春晓", poem-id: "chunxiao"),),
    ),
  ),
)

Every poem referenced from author-index must have a matching poem-id in the chapter data so its page reference can be resolved.

chapters and poems

chapters: (
  (
    name: "第一编 春晓",
    subname: "五言绝句",
    bg-color: "#E65100",
    poems: (
      (
        number: 1,
        poem-id: "chunxiao",
        title: "春晓",
        author: "（唐）孟浩然",
        lines: ("春眠不觉晓，处处闻啼鸟。", "夜来风雨声，花落知多少。"),
        notes: (
          (headword: "晓", text: "天刚亮的时候。"),
          (headword: "闻", text: "听见。"),
        ),
      ),
    ),
  ),
)

• poem-id is optional, but it is required for pinyin annotations and author-index page references.
• notes is required; use () when a poem has no notes.
• topic and subtopic are optional grouping headings within a chapter.

Pinyin annotations

Pinyin data is passed separately:

#let pinyin = json("pinyin.json")
#show: poem-book.with(
  book: book,
  pinyin: pinyin,
  pinyin-mode: true,
)

pinyin-mode forces a single column and larger type. The JSON shape is:

{
  "version": 1,
  "poem-count": 1,
  "poems": {
    "jingyesi": {
      "title": [["静", "jìng"], ["夜", "yè"], ["思", "sī"]],
      "author": [["李", "lǐ"], ["白", "bái"]],
      "lines": [
        [["床", "chuáng"], ["前", "qián"], ["明", "míng"], ["月", "yuè"]],
        [["疑", "yí"], ["是", "shì"], ["地", "dì"], ["上", "shàng"], ["霜", "shuāng"]]
      ]
    }
  }
}

Each title, author, and line is an array of [hanzi, pinyin] pairs. The key under poems must match the poem’s poem-id.

poem-book parameters

Page profiles

Fonts

The template uses Noto Serif CJK SC for body text and STKaiti or KaiTi for titles, with Noto Serif CJK SC as the final fallback. Install a CJK font before compiling. On Debian/Ubuntu, install fonts-noto-cjk; on macOS and Windows, the system KaiTi/STKaiti fonts can be used. If a font is unavailable, Typst falls back to another installed font and emits a warning.

Template contents

The template ships with four public-domain poems (春晓, 静夜思, 登鹳雀楼, 咏鹅) and neutral example data. Replace the chapters, appendix, and front-matter entries with your own content. No real school name, logo, or curriculum is included.

License

MIT. See LICENSE.