独立季刊

---
name: quarterly-magazine
description: 为独立杂志、期刊或通讯做一个完整的离线网站：一个 HTML 文件，用井号路由，全部页面由一段 JSON（文章、栏目、商品、订阅方案）渲染。凸版印刷的观感：暖色纸底、一种油墨加一种专色，刊头随期号变化，头版是印在折页上的海报式目录，木刻版画由每篇文章的数据生成。搜索、筛选、收藏、小铺、购物袋、演示结账和演示订阅都真能用，且不收任何款项。当有人要做杂志、期刊、小刊物或通讯网站，要带小铺的内容站，或点名要这个风格时使用。
version: 1.0.0
---

# 独立季刊

样式和所有功能都在 `assets/template.zh.html`（中文）和 `assets/template.html`（英文）里。你只需要写一份 JSON 稿件，`scripts/fill.mjs` 把它放进模板，引擎据此画出全部页面。不要改样式、引擎和界面文字，`scripts/check.mjs` 会逐字节和模板比对。

具体的色值、字号、动效和该做不该做的事，见 `references/style.md`。那份文件只有英文，里面都是数值和规则，照常规流程不需要改样式。

## 需要问的内容

稿件没写到的，一次问完。

必填：
1. 刊名。
2. 写什么，一句话。
3. 期号。季节或日期有真实的才要。
4. 文章的真实文字：标题、一两句导语、栏目、正文，有作者就给作者。
5. 栏目，每个配一句说明。

可选：编者的话；关于页文字和编辑部成员；联系邮箱、地址或备注；商品和价格；订阅方案；常见问题；用来替换版画的图片；语言（英文版用英文模板）。

## 步骤

1. 按「字段」一节给出的结构写 `brief.json`。中文版加上 `"lang":"zh"`。需要的信息都在本页；这个包的样例不在安装内容里。
2. `node scripts/fill.mjs brief.json output/index.html`
3. `node scripts/check.mjs output/index.html --shots shots/` 有问题就改稿件，重跑到通过。六篇文章的站点每次约一分钟。
4. `node scripts/drive.mjs output/index.html` 在三种宽度、开关动效下把每个功能都走一遍，约一分钟。
5. 打开 `shots/` 里的每一张截图逐张看：1280、768、390 三种宽度下的每条路由，搜索、购物袋、菜单这些浮层，以及 `state_` 开头的状态图：`saved_filled`、`checkout_blank`、`checkout_errors`、`checkout_filled`、`receipt_checkout`、`subscribe_errors`、`receipt_subscribe`、`contact_errors`、`contact_note`。读着别扭的就改文字，不要动 CSS。检查脚本还会拦下这些情况：期号贴着刊名、笔画下伸碰到下方内容、一栏内部有 140 px 以上的空白、页脚下有空带、同一篇文章在栏目页出现两次、正文末行只剩一个字。

运行要求：Node 18 或更高。check 和 drive 需要 Playwright：`npm install playwright && npx playwright install chromium`，或者把 `NODE_PATH` 指向装有它的 `node_modules`。没有它时 `check.mjs` 以退出码 3 结束并说明原因。`--static` 只查数据，不算通过。不需要联网，不需要构建，也没有其他依赖。产物是一个文件，约 210 KB 加上你的文字。

## 字段

长度按字符计，中日韩字符算 2，检查脚本会逐项核对。没有真实内容的可选字段直接不写，页面就不显示那一部分，不存在需要填的占位内容。没有 `products`、`plans` 或 `faq` 就整段删掉。最小可用的结构：

```json
{
  "lang": "zh",
  "site": { "name": "", "short": "", "tagline": "", "issue": { "number": 1 }, "fictional": false, "currency": "¥" },
  "topics": [ { "id": "", "name": "", "blurb": "" } ],
  "stories": [ { "id": "", "title": "", "dek": "", "topic": "", "body": ["第一段。", { "h": "小标题" }, "下一段。"] } ],
  "products": [ { "id": "", "name": "", "price": 12, "blurb": "" } ],
  "plans": [ { "id": "", "name": "", "price": 0 } ],
  "faq": [ { "q": "", "a": "" } ]
}
```

### site
| 字段 | 含义 | 上限 | 内容不足或缺失时 |
|---|---|---|---|
| `name` | 全称，用作刊头。必填 | 60 | 去问。名字长会分成最多三行；名字极短时，刊头其余位置由版画带填满 |
| `short` | 顶栏显示的名字。`name` 超过 16 时必填 | 16 | 用平时的简称；没有就取名字里最主要的部分 |
| `tagline` | 写什么。出现在刊头下方和关于页 | 90 | 复述用户自己的说法 |
| `issue.number` | 整数，决定刊头和配色。必填 | 1 到 999 | 还没出过刊就写 1 |
| `issue.label` | 可选。季节或日期，如「立冬号」 | 24 | 不写，刊头下方只显示期号。不要编日期 |
| `fictional` | 内容是编的就必须为 true，真实刊物为 false。必填 | true 或 false | 为 true 时，顶部提示、页脚、常见问题自动带上虚构标注 |
| `notice` | 替换顶部提示条的文字。`fictional` 为 true 时必须自己写明「虚构」 | 120 | 不写 |
| `currency` | 价格前的符号 | | 默认 `$`，人民币记得写 `¥` |
| `press` | 固定配色：`prussian`、`bottle`、`aubergine`、`soot` | | 不写，配色随期号轮换 |
| `letter` | 首页的编者的话，换行即分段 | 500 | 不写，折页就只显示两栏 |
| `about` | 关于页段落的数组 | | 不写，关于页只显示一句本文件收录的篇数和栏目数 |
| `staff` | `{name, role}` 数组 | | 不写。真实刊物不要编人名 |
| `contact` | `{email, address, note}` | | 缺哪项就不写哪项，页面会说明暂未公开地址，虚构刊物一般也这样最好。真实刊物不要编地址。虚构刊物如果写了以 `.invalid` 结尾的邮箱，页面只显示文字，不给邮件链接 |
| `verifiedClaims` | 只有用户明确提供了奖项或读者数字时才设为 true | | 不写 |

### topics（至少一个）
`id`（a-z、0-9、连字符）、`name`（28）、`blurb`（160）。用户没给栏目时，按刊物主题定一个，并在交付时列为推断内容。没有文章的栏目不进首页列表，但页面还在。

### stories（至少一篇）
`id`、`title`（80）、`dek` 导语（170）、`topic`（栏目 id）、`body`，以及可选的 `author`（40）、`issue`（默认当期）、`date`（24）、`image` 和 `imageAlt`、`plate`（`{comp, motif}`）、`short`。

`body` 是数组。字符串是一段，`*词*` 表示强调：中文显示为专色加字下着重点，英文显示为斜体。对象有：`{"h":"小标题"}`、`{"q":"引语"}`、`{"list":["甲","乙"]}`、`{"note":"边注"}`。

- 只放真实文字。每篇至少 150 个汉字或 80 个英文词。用户只给了一小段，就保留原话并设 `"short": true`，不要扩写凑数。
- 没有导语：用文章的第一句。没有作者：不写 `author`，页面就不显示作者。作者和刊名相同时同样不显示。
- 文章少：一篇也可以。海报和网格会按实际篇数排，不会留空位。不要为了填满而加文章。
- 标题长：超过 34 个单位会改用瘦高字体，最多三行。检查脚本提示某行缩得太小，就把标题改短。

### products（可选，名称 44，简介 200）
`id`、`name`、`price`（数字）、`blurb`、`details`（数组）、`options`（数组）、`optionLabel`、`plate`、`image`、`imageAlt`。没有商品时，小铺、购物袋和结账从全站消失，它们的地址显示 404 页。

### plans（可选，名称 28，周期 20，简介 110）
`id`、`name`、`price`（必填），以及可选的 `period`、`blurb`、`includes`。没有方案时，订阅同样消失。

- `price`：数字。0 会用大字显示「免费」；如果方案名里已经有「免费」，就不再重复，所以方案可以直接叫「免费」。
- `period`：这个价钱管多久，比如「每年」「每季一封」。用户没说就不写，也不要在这里再写一遍「免费」。
- `includes` 和 `blurb`：只写用户说过的权益。用户只给了名字和价格，这两项都不写，卡片照样完整。不要编权益，推断的内容要列给用户。

### faq（可选，问题 90，回答 400）
`q`、`a`。你写的排在前面。关于演示小铺、演示订阅和收藏存放位置的说明总会自动加上；`fictional` 为 true 时还会加上虚构说明。

## 路由

`#/` 首页，`#/stories`（`?topic=`、`?issue=`、`?view=grid|index`），`#/story/<id>`，`#/topics`，`#/topic/<id>`，`#/saved`，`#/shop`，`#/shop/<id>`，`#/checkout`，`#/subscribe`（`?plan=<id>`），`#/about`，`#/contact`，`#/faq`。其他地址都显示设计好的 404 页。按 `/` 键打开搜索，Esc 关闭任何浮层。

## 自动行为

- **刊头：** 期号除以 4 的余数决定排法和配色：0 期号在右，prussian；1 期号在左，bottle；2 反白油墨块，aubergine；3 刊名用专色，soot。期号数字和刊名下的花边也随期号变化。
- **头版海报：** 列出当期文章，最多九篇，每行撑满全宽。标题短时字号到上限就停，余下位置由版画条填满。往期变成一个「往期还有」链接。
- **版画：** 每篇文章和每件商品的木刻图由其 id、标题、导语、栏目和正文生成，构图和纹样各不相同。标题或导语里的词会尽量决定纹样（水对应水波，火对应放射线，墙对应砖纹），十二种纹样用完之前不重复。字母版画只用笔画够多的字，跳过「一」「I」这类单薄的字；一个合适的都没有就改成圆章构图。把 `plate.comp` 固定为 `letter` 时也按这条规则。`plate.comp` 可选 horizon、quilt、arch、diagonal、medallion、strata、letter、columns。`plate.motif` 可选 waves、scales、chevrons、reeds、bricks、rays、hatch、rings、diamonds、gouges、rope、ripples。`image`（页面旁边的本地文件或 data URI）会在所有位置替换版画。
- **栏目页：** 最新一篇做头条，其余进归档，只有一篇时就没有归档。单张卡片会占满一行，并带上第一段的摘录。
- **折页：** 文字留下的高度由版画带填满，所以栏目少或没有编者的话也不会留空。
- **页脚：** 短页面上也贴在窗口底部。
- **末行：** 正文最后几个字或最后一个词不会被拆开落单。
- **排序：** 最新一期在前，同期按稿件顺序。**阅读时长** 按正文自动计算。
- **存在浏览器里的：** 收藏、购物袋、图版或目录视图的选择、演示单编号。
- **演示流程：** 结账和订阅会校验表单，然后在页面上显示一张带编号的演示单，写明没有扣款、没有发出任何东西，全程没有银行卡一栏。联系表单只把话排在页面上；有联系邮箱时提供一个打开邮件应用的链接。不要改这些文字。用户要真收款的情况见下文。

## 拿不准的时候

- 稿件太薄：复述用户给的事实，不要编。交付时列出每一条推断内容。
- 没人能回答：先做，并列出你的假设。
- 没有真实链接或地址：字段不写。
- 长度不同：文章长短听用户的，没有上限，再长也是同一个阅读栏。
- 给真实客户用样稿或编造的内容：在真实文字到位之前，把 `fictional` 设为 true。

## 交付前

- [ ] `check.mjs` 不带 `--static` 通过
- [ ] `drive.mjs` 通过
- [ ] 1280、768、390 三种宽度的每张截图都看过，包括浮层和 `state_` 状态图
- [ ] 每篇文章都是用户的真实文字，或已标注为虚构
- [ ] 没有编造读者评价、读者数字、奖项或媒体引语
- [ ] `fictional` 设置正确；为 true 时顶部提示、页脚和常见问题都有标注
- [ ] 推断内容已列给用户
- [ ] 全站只用一种语言

## 不适合的情况

- 日更新闻站，或有几百篇文章的刊物：所有内容都在一个文件里。
- 必须真实收款的小铺，或必须真实发信的订阅：这里没有后端。可以把它当作设计稿，再请开发者接入真实服务并替换演示文字。
- 以照片为主的杂志：图片可以替换版画，但这套设计是围绕字体做的。