A data-driven Chinese poetry reader for Typst. It provides A4/A5/A6 page profiles, one- or two-column layouts, a large-print two-poems-per-page layout, pinyin ruby annotations, short notes under each poem, chapter covers, a table of contents, and optional appendix pages for poet biographies, famous lines, an author index, and endnotes for disputed readings.
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.2.0 my-poetry-book
cd my-poetry-book
typst compile main.typ
Or import the package directly:
#import "@preview/shiyin-reader:0.2.0": poem-book
#let book = json("book.json")
#show: poem-book.with(book: book)
Data model
Book dictionary
| Key | Type | Required | Description |
|---|---|---|---|
metadata |
dictionary | yes | Title and edition information. |
format |
dictionary | yes | Page size, columns, type sizes, and leading. |
notes |
dictionary | yes | Note mode. Currently mode: "short". |
fonts |
dictionary | yes | Body and title font fallback lists. |
chapters |
array | yes | Chapters, each containing poems. |
branding |
dictionary | no | Optional school or organization branding. |
features |
dictionary | no | Optional appendix pages; all default to false. |
front_matter |
dictionary | no | Preface text. Required when features.front_matter is true. |
appendix |
dictionary | no | Data for the optional appendix pages. |
metadata
| Key | Type | Description |
|---|---|---|
title |
string | Book title (required). |
volume |
string | Volume or grade label. |
edition |
string | Edition year or label. |
version |
string | Optional version label shown after the edition on the cover, e.g. v0.3. |
author |
string | Document author. Defaults to the book title. |
cover_mode |
"general" or "personal" |
personal adds name and class fields to the cover. |
student_name, class_name |
string | Values used in personal mode. |
review_mode |
boolean | Show a review label on the title page. |
review_label |
string | Review label text. Defaults to 审核稿. |
format
| Key | Type | Description |
|---|---|---|
paper |
"a4", "a5", "a6" |
Page size. |
columns |
1 or 2 |
Column count. |
gutter_pt |
number | Column gutter in points. |
body_size |
number | Body text size in points. |
leading |
number | Paragraph leading multiplier. |
note_size |
number | Note text size in points. |
note_leading |
number | Note paragraph leading multiplier. |
poems_per_page |
number | Poems per page. 1 is the normal flow; 2 stacks two equal panels per page. |
panel_gap |
number | Gap between the two panels in points when poems_per_page is 2. |
compact_fit |
boolean | Tighten note and heading spacing before giving up on a two-up pair. Body size never shrinks. |
poem_title_size, author_size, poem_gap |
number | Title, author, and inter-poem spacing in points. |
pinyin_body_size, pinyin_note_size, pinyin_size, pinyin_leading |
number | Pinyin-mode body, note, ruby, and leading overrides. |
pinyin_title_size, pinyin_title_pinyin_size, pinyin_author_size, pinyin_author_pinyin_size |
number | Pinyin-mode title and author overrides. |
margin_left_pt, margin_right_pt, margin_top_pt, margin_bottom_pt |
number | Pin reading margins independently of the theme. |
aux_scale |
number | Scale factor for appendix pages. |
title_size, title_pinyin_size, author_size, author_pinyin_size, pinyin_size |
number | Legacy pinyin overrides kept for compatibility. |
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.
| Key | Type | Description |
|---|---|---|
school_name |
string | School or organization name. |
school_name_en |
string | Secondary name, usually English. |
slogan |
string | Cover and back-cover slogan. |
motto |
string | Vertical motto on the back cover. |
cover_lines |
array of strings or string | Lines shown in the middle of the cover in general mode. |
logo |
string or image | Logo image. Typst callers can pass image("logo.svg"), which resolves in their project. JSON callers pass a path string, resolved from the package file; use an absolute path or the asset-root prefix. |
end_motto |
string | Ending-page motto. Defaults to 诗心常在 书香长伴. |
features
| Key | Default | Description |
|---|---|---|
front_matter |
false |
Render the preface page. |
famous_lines |
false |
Render the famous-lines appendix. |
poet_bio |
false |
Render the poet biographies appendix. |
author_index |
false |
Render the author index. |
reading_notes |
false |
Render the endnote appendix for disputed or easily misread characters. |
end_page |
false |
Render the closing page. |
back_cover |
false |
Render the back cover. |
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"),),
),
),
reading_notes: (
heading: "【后注】",
subtitle: "多音字与异读备查",
intro: "正文按教材或通行读法标注;下列异读供教师和家长备查。",
groups: (
(
heading: "一、多音字示例",
items: (
(
poem: "《春晓》",
word: "不觉晓",
reading: "bù jué xiǎo",
alternative: "bù jiào xiǎo",
note: "“觉”在这里是“觉察、发觉”,读 jué。",
),
),
),
),
),
)
Every poem referenced from author_index must have a matching poem_id in the chapter data so its page reference can be resolved.
reading_notes groups contain heading and items; each item has poem, word, reading, an optional alternative, and a note. The page is rendered when features.reading_notes is true.
chapters and poems
chapters: (
(
name: "第一编 春晓",
subname: "五言绝句",
bg_color: "#E65100",
poems: (
(
number: 1,
poem_id: "chunxiao",
title: "春晓",
author: "(唐)孟浩然",
lines: ("春眠不觉晓,处处闻啼鸟。", "夜来风雨声,花落知多少。"),
notes: (
(headword: "晓", text: "天刚亮的时候。"),
(headword: "闻", text: "听见。"),
),
),
),
),
)
poem_idis optional, but it is required for pinyin annotations and author-index page references.notesis required; use()when a poem has no notes.topicandsubtopicare 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
| Parameter | Default | Description |
|---|---|---|
book |
required | Book dictionary. |
format |
none |
Override book.format. |
notes |
none |
Override book.notes. |
fonts |
none |
Override book.fonts. |
features |
(:) |
Override book.features. |
cover-mode |
none |
Override metadata.cover_mode. |
asset-root |
"" |
Prefix for branding.logo. |
pinyin |
none |
Pinyin dictionary. |
pinyin-mode |
false |
Enable ruby annotations and single-column layout. |
design |
"school" |
Reading-page structure. "school" keeps the original layout; "kami" is accepted as a compatibility alias. |
palette |
none |
Colour palette applied over the structure: "school" (default) or "kami" (warm paper and ink blue). |
Page profiles
| Paper | Margins (left/right/top/bottom) | Status |
|---|---|---|
| A4 | 22/20/21/20 mm | Production target. |
| A5 | 20/17/19/18 mm | Supported; visual acceptance is still in progress. |
| A5 (Kami) | 20/20/26/18 mm | Kami reading layer: top-heavy margins, two columns. |
| A6 | 18/14/16/15 mm | Supported; visual acceptance is still in progress. |
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.
The kami design uses LXGW WenKai for both body and titles, so the reading pages keep a single serif family. Install LXGW WenKai before compiling Kami editions.
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.