章 5 · 篇 II · 工艺
文档格式
Postext能解析哪些Markdown写法(前置元数据、标题、列表和代码块),哪些写法会被忽略,以及写源文档时要遵守的规则
简单来说
本页说明怎样写出Postext能排版的文字。文字用Markdown写成,这是一种简单的写法,用几个符号标出标题、列表、粗体和链接。本页讲文件开头的几行、标题、列表、代码,以及Postext会忽略的标记。另有四页分别讲框和分栏这类块、行内的标记、注释和引用,以及图片和表格。最后给出一些让文字更好读的建议。
Postext读取的是一种有意保持精简的Markdown方言。
解析器是手写的分词器,并不是完整的CommonMark实现,所以源格式的范围窄,行为也容易预测。这样做有两个目的:让引擎保持小而快;让文档可以毫不费力地在Postext与其他CommonMark阅读器(Obsidian、Pandoc、VS Code……)之间通用。本页没有列出的写法,要么按纯文本处理,要么从行内文本流中移除。
如果你用程序构建文档,parseMarkdown函数(见配置 › 解析)会给出排版引擎实际使用的块结构。
#前置元数据
文档开头可以放一段YAML前置元数据(可选),上下各用一行---标出:
---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---
# Chapter One
The story begins here…调用extractFrontmatter(source)可以把前置元数据和正文分开。它返回解析后的元数据对象、其余的Markdown,以及正文起始处的字符偏移量;如果你需要把错误或光标位置映射回原始源文本,这个偏移量就很有用。
前置元数据由gray-matter解析,因此任何结构的YAML都能接受。Postext本身只看title、subtitle、author和publishDate;其他键保留在PostextContent.metadata上,供你自行使用。
如果这一段不是有效的YAML(例如引号没有闭合,或带引号的值后面还有文字),排版也不会中断:extractFrontmatter不返回元数据,把结束的---之后的文字作为正文,并在error中给出解析器报告的原因。文档照常排版,只是没有元数据;构建结果在contentWarnings中列出一条invalidFrontmatter(沙盒中显示为前置元数据无效)。
YAML会给值赋予类型:1984是数字,2026-04-15是日期,[Ana Gil, Luis Paz]是列表。无论类型如何,Postext都把这四个字段作为文本输出:
- 数字按普通十进制形式输出,布尔值输出为
true或false(title: 1984输出1984)。YAML把数字当作一个值来读,而不是逐位读取:1.50输出1.5,017(八进制)输出15,1:30(六十进制)输出90; - 日期输出为对应的日历日期,用文档的语言书写(即
locale设置,未设置时取断词语言):publishDate: 2026-04-15在英文中输出April 15, 2026,在西班牙文中输出15 de abril de 2026,在德文中输出15. April 2026。阿拉伯文日期使用公历,除非标签指定了别的历法(ar-u-ca-islamic输出伊斯兰历日期),用哪种数字也由标签决定(ar-EG:١٥ أبريل ٢٠٢٦;ar-u-nu-latn:15 أبريل 2026)。带时刻的日期按UTC时间取日期,并舍去时刻:2026-09-24T23:30:00-05:00是25日UTC 04:30,输出September 25, 2026; - 列表输出为用逗号连接的各项(
author: [Ana Gil, Luis Paz]输出Ana Gil, Luis Paz)。
给值加上引号,就会按写的样子原样输出。数字要保留每一位、日期不能变动时,就这样写:publishDate: "15/04/2026"、title: "1984"。这段文本会进入doc.metadata、占位符({title}、{publishDate}……)以及PDF的标题和作者。这四个字段的值如果没有文本形式(嵌套映射、空的title:),就不会出现在doc.metadata中。extractFrontmatter仍按YAML赋予的类型返回这些值;metadataText(value, locale)返回Postext为某个值输出的文本。
#块结构
Postext识别七种正文块类型和代码清单,另外还有指令和资源嵌入,它们各有专页介绍。块总是在空行处或下一个块开始处结束。
| 结构 | 语法 | 说明 |
|---|---|---|
| 标题 | # Title … ###### H6 | 一到六个#字符,后跟一个空格和标题文本。1–6级直接对应headings.levels配置。 |
| 段落 | 一行或多行纯文本 | 连续的非空、非特殊行用一个空格连接,作为一个段落输出。在两个中文或日文字符(表意文字、假名、全角标点,以及紧挨它们的弯引号、破折号或省略号)之间,换行符则直接去掉,与CSS的做法相同,因此中文段落在源文本中可以在任意位置换行。在两个这样的符号之间(“你好”⏎“再见”、他说……⏎“好”),由符号外侧的字符决定:其中一个是中文或日文时,换行符去掉;“hello”⏎“bye”则保留空格。韩文保留空格。源文本中输入的换行不会保留,除非该行以反斜杠结尾(强制换行,见段落内的换行);要开始新段落请用空行。在文字中输入的制表符同样当作词间空格,除非段落的样式设了制表位;:tab总是制表符(见制表符与制表位)。诗歌的各行必须保持原样,应放进:::verse块。 |
| 引用块 | > quoted text | 引文的每一行都必须以>开头(后面可有一个空格)。连续的引文行合并为一个引用块,连接方式与段落行相同。它按bodyText.blockquote的设置排版:除非你修改,否则为灰色斜体,并带有正文的首行缩进(见配置 › 引用块)。 |
| 无序列表 | - item、* item、+ item | 三种项目符号都可以使用。列表项的标记比上一项的标记至少右移两列时,就嵌套在上一项之下:在-下缩进两个空格,在1.下缩进两个或三个空格(即其正文所在的列,与CommonMark相同),最大深度为5。 |
| 有序列表 | 1. item、2) item | 数字后跟.或):欧洲数字,或阿拉伯语、波斯语键盘打出的阿拉伯-印度数字(١.)和波斯数字(۱.)。起始编号会保留(列表可以从5开始,也可以从0开始)。输出中显示的分隔符来自orderedLists.separator,而不是源文本。 |
| 任务列表(GFM) | - [ ] todo、- [x] done | 带方括号复选框的无序列表项。小写x和大写X均可。方框由引擎绘制,任务完成时带一个勾;在taskCheckboxChar / taskCheckedChar里指定的字符则作为文字排在它的位置。 |
| 行间公式 | $$ … $$ | 单独成块排版的LaTeX公式。在栏内居中渲染,像标题一样对齐基线网格,在PDF输出中保持矢量。单行形式和围栏多行形式见数学公式。 |
| 代码块 | 、~~~ … ~~~ | 一段代码清单,按原样保留:每个空格、制表符和换行都保留,其中的内容都不按Markdown读取。用代码字体逐行排在框中。见代码块。 |
两个列表项之间有一个空行是允许的,列表仍保持连续。两个或更多空行则结束列表。
同一深度上可以混用不同类型的列表(可以在中途从无序切换为有序),但引擎在编号时把它们当作各自独立的列表。实际使用中,除非确有需要,每个深度最好只用一种类型。
#标题属性
标题行末尾可以加一个用花括号括起的属性块,语法与指令的key="value"相同:
# The Long Road {author="I. Zango Martín" year=1998}花括号及其内容会从标题文本中去掉(上例的标题显示为The Long Road),作为attrs存在标题上。设计槽位可以用{attr.<key>}占位符取用它们:一处是标题自身的高级设计槽位,另一处是页眉和页脚,后者从当前章的H1取值。Postext只识别位于行尾、括号配对且内部不含花括号的块;块前须有一个空格,或者紧跟在中文或日文字符之后,因为中文标题本来就不加空格(# 回目{style="x"})。只有下文的属性语法能读完整个块时,它才算属性块:{x, y}、{紅樓|hóng lóu}和单独的{}都留在标题中,紧贴标题且只有标志的块(# 第一回{draft})也一样。属性之间用空格分隔,因此带逗号的块({a="1", b="2"})以及Pandoc的{.class}也留在标题中。Pandoc的标识符{#id}可以识别:它等同于id="…",给标题起一个名字,供交叉引用使用。用其他文字书写的键会被读取,然后丢弃并给出警告(见下文),所以# 回目{style="x" 作者=曹雪芹}仍会采用style。见配置 › 页眉与页脚。
设计文本输出的值可以占多行:两个字符\n表示在此换行,与元素的overflow设置无关(to="Firma X\nStrasse 1\n10115 Berlin"输出三行地址)。元素设置了inlineMarks时,值中的行内标记也会生效:authors="Ana Ruiz^1^, Luis Gil^2^"会把作者单位编号排成上标。这种转义只用于属性值(以及设计本身的模板):标题文本里的\n字符(比如写在行内代码中)会原样输出。
有两个属性有特殊含义。style="<id>"给标题套用一个命名的标题样式,例如前言或作者名单,它有自己的章首页设计、书眉、页面几何和正文排版;样式设为numbered: false时不带章号。toc="false"(或"true")决定该标题是否列入:::toc生成的目录:
# Preface {style="front-matter"}
# Contents {style="front-matter" toc="false"}另外几个属性改变标题输出的内容和计数方式。hidden="true"(或"false")覆盖标题所在级别或样式的hidden:隐藏的标题不输出任何内容,也不占空间(在正文流中和:::callout框内都是如此),但仍照常起页、参与计数,并列入目录、{chapterTitle}书眉和PDF书签。jidori=N把单行标题均匀拉开到标题自身的N个字宽(字取り:# 序章 {jidori=3}印作序 章),jidori=0关闭其级别或样式设定的均排(见配置 › 按级别覆盖)。indent=N让单个标题从行首缩进正文的N个字(字下げ:## 一 {indent=5}),覆盖其级别或样式的indent;不带单位的数字按正文字宽计,0让标题回到行首,竖排和横排都适用。firstLineIndent=N只缩进单个标题的第一行,覆盖其级别或样式的firstLineIndent,其余各行从indent定下的位置起排(GB/T 9704的标题:## 关于加强管理的通知 {firstLineIndent=2});长度的读法与indent相同,0取消级别上的设定。startAt=N(正整数)把该标题所在级别的计数器直接设为N,而不是加一;其后的标题从这里接着计数,后面各章也一样,下级标题照常在它之下重新计数。如果标题样式用字母给附录编号(numberingTemplate: 'Appendix {1:A}'),可以让第一个附录重新开始计数,读作Appendix A,而不是接着各章往下数:
# To my mother {hidden="true" toc="false"}
# Survey instrument {style="appendix" startAt=1}
# Raw data {style="appendix"}#首字下沉
如果段落前面标题的级别或样式,或者段落所在:::paragraphs组的段落样式设了首字下沉,段落就以首字下沉开头(见配置 › 首字下沉):第一个字母放大,排在前几行旁边,这几行让出位置,相应缩短。段落本身不需要任何标记,文字照常书写;复制、搜索和源映射时,这个字母仍属于它所在的词。用dropcap属性可以为某一章或某一组单独开关首字下沉:
# Lost {dropcap=false}
# The mines {dropcap=2}
:::paragraphs{style="entry" dropcap}
The lamp of the first entry opens with an initial.
:::在标题行上,dropcap=false让该标题后的段落不带其级别或样式设定的首字下沉,dropcap=N把首字下沉设为N行,级别没有设定时,单独写dropcap也会给这一段加上首字下沉(三行,用段落的字体)。写在:::paragraphs的开始行上时,这个属性对组的第一段起同样的作用;样式设为each: true时,则对每一段都起作用。查找标题后的段落时,会跳过围栏、指令、已移出正文流的框和浮动插图;框、列表项、引文或诗歌中的段落从不带首字下沉。自postext 1.23起。
在模板页里,框中排的是正文:框里的:::paragraphs{style="kaitou" dropcap}会让它的第一段以首字下沉开头。:::callout框里的段落不带首字下沉,在框里要求首字下沉会引发dropCap警告。
#代码块
代码清单写在两条由三个或更多反引号(或三个或更多波浪号)组成的围栏之间,每条围栏单独占一行,最多缩进三个空格。两条围栏之间的内容都按原样保留:行首空格和连续的空格、制表符、空行,以及以#、-、1.、>、$或:::开头的行。其中的内容一概不按Markdown解读:强调、:ref、公式、行内标签、指令和标题都不起作用。结束围栏所用的字符与开始围栏相同,长度至少与它相等;所以清单本身要显示围栏时,就用更长的围栏或波浪号围栏把它围起来:
```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copy the photos to the backup disk
rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/
echo "done: $(date)"
```开始围栏后面的信息字符串指明语言(取它的第一个词:js、ts、python、bash、console、json……),其余部分按属性写法读作属性,属性加不加花括号都可以(title="app.js" lineNumbers)。语言之后的其他文字是标题:```console Terminal和```python normalize.py在清单上方印出Terminal和normalize.py。
| 属性 | 作用 |
|---|---|
title="…" | 清单上方的标题,排在标题行中(设了codeStyle.label时排在框边的页签中)。 |
label="…" | 框边页签上的文字,用法与:::callout的页签相同(需设codeStyle.label)。 |
lineNumbers、lineNumbers=false | 为这段清单的行编号(或不编号),不管codeStyle.lineNumbers怎样设置。行号排在代码前面单独的一栏里,复制代码时不会带上。 |
start=N | 第一行的行号(即使没有别的设置开启行号,它也会让清单带上行号)。 |
highlight="3,5-7" | 为指定的行加底色(从清单第一行起算,第一行记为1):可以写单独的行或范围,用逗号分隔。 |
span=page | 在分为几栏的页面上,清单横跨所有栏。 |
placement=top, placement=bottom | 让清单像浮动的 :::callout 一样浮到某栏顶部或底部的第一个空闲带。 |
围栏会结束它上面的段落,不论中间有没有空行;结束围栏之后的文字开始一个新段落。没有闭合的围栏一直延续到文字末尾,并给出警告(unclosedCodeBlock)。:::callout中的围栏成为嵌套在其中的框;在:::paragraphs中,清单保持代码样式,不采用段落样式。Postext不支持在列表项下接续内容,所以列表项之后的围栏会结束列表。写在清单中的索引标记和锚点照原样保留。
缩进代码(空行之后以四个空格或一个制表符缩进)只有在打开codeStyle.indentedCode时才读作代码清单:Postext的正文常用空格缩进,而列表项正是靠行首空格来嵌套的。
清单的外观(字体、框、制表符宽度、比框更宽的行如何处理、行号、各类语法元素的颜色)由codeStyle设定,见配置 › 代码清单。行内代码(`x`)沿用正文字体,除非codeStyle.inline另外指定字体。postext 1.23之前保存的书如果正文里有围栏,仍按当时的方式把它们当作Markdown读取(codeStyle.blocks: false)。自postext 1.23起。
#不支持的内容
Postext不识别以下CommonMark功能。它们要么被当作普通文本(因此会原样出现在输出中),要么直接丢弃,不给任何提示:
- Setext式标题:即
===/---下划线形式。请使用ATX(#)标题。 - HTML透传:Postext不解释原始的
<tags>,也不支持MDX式标签;Postext源文件是纯Markdown。 - 水平线:
---、***、___。 - 表格:不解析管道表格。表格以结构化资源的形式放在
PostextContent.resources中。 - 引用式链接:
[text][id]加上定义块。 - 自动链接:
<https://example.com>。 - 用行末两个空格表示的换行:这两个空格会被删去。请改在行末写反斜杠(见段落内的换行)。
- 旁注:尚未实现;类型定义虽然接受
PostextContent.notes,引擎却会忽略它。脚注和章末注用[^id]书写(见脚注);在postext 1.5及以前,它们只能作为文本排出。
这份清单会随时间缩短。在此之前,凡是上文没有明确列为支持的写法,都应当视为原样输出的文本。
除语法之外,阿拉伯文和其他从右向左书写的文字从右向左排版,采用双向算法,书在右侧装订(见阿拉伯文排版)。中文可以横排,也可以竖排,并按所在地区的要求处理断行、标点宽度、字间两端对齐、着重号等标记、注音和双行夹注(见中文排版)。日文按自己的规则排版,包括禁则、约物间距、振假名、傍点、汉文训读记号和注释(见日文排版);韩文使用同一个排版器,按中国大陆的中文规则排版。Postext自带八种语言的断词模式,并为这八种语言以及中文、日文和阿拉伯文提供内置标签。见语言与文字。
#书写约定
遵守下面几条约定,文档就能顺利解析,不会出现意料之外的结果:
- 块与块之间留一个空行。用空行隔开的两个段落是两个段落。写在相邻两行的两个段落会合成一段:每一行都并入前面的段落。
- 多余的空行不会增加空白。用三个空行隔开两个块,效果与一个空行完全相同。想在两个块之间多留些空白时,写一行
:::space。 - 嵌套的列表项缩进到上一项正文的位置。在项目符号(
-)下缩进两个空格,在1.下缩进三个,在10.下缩进四个,与CommonMark的嵌套方式相同;在1.下缩进两个空格也算嵌套。列表项会嵌套在最近的一个未结束的列表项之下,前提是那一项的标记比它至少靠左两列;因此只缩进一个空格不构成嵌套,而且无论每级缩进多少,都不会跳级(postext 1.15及以前的深度为floor(空格数 / 2) + 1,1.下的1.会排成第4级)。制表符把位置推到下一个4的倍数列。最大深度为5。 - 第一个列表项不要缩进。第一级列表项从第0列开始。列表的第一项无论缩进多少都是第一级(postext 1.15及以前,行首空格会提高它的级别),所以要嵌套,上方必须先有一个列表项。
- 任务标记必须写在方括号里,中间一个空格。只能是
[ ]、[x]、[X],不能有其他写法。[*]或[-]不是任务标记,会原样作为文本输出。 - 不支持列表中的引用块。引用块要从第0列开始,写在列表之外。
- 图片和表格放在
resources中。行内的会被去掉,原因正是行内图片会打乱按栏放置的逻辑。把每张图片声明为资源并按id引用,再由引擎决定它是浮动、截断所在的栏,还是移到下一页顶部。 - 不表示公式时,用
\$转义美元符号。Postext把$…$当作行内LaTeX,所以正文中单独的$会被当作公式的开头。价格、shell提示符以及其他带单独美元符号的内容都应写成\$。 - 标记用ASCII字符键入,中文和日文文本中也一样。中文或日文输入法打出的是全角形式:指令的冒号成了
:::,标题成了#,脚注标记成了[^1],属性成了{…},粗体成了**。它们会作为文本印出,构建时该行会报出fullwidthMarkup警告,并指出应当键入的ASCII形式。属性值可以用任何文字书写,也可以用“…”或「…」加引号;键名仍须是ASCII。
#完整示例
一份用到所有受支持结构的短文档:
---
title: The Typesetter's Craft
author: Anon
---
# Opening
A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.
## What makes text readable
Three properties matter most:
1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
1. Tighter at short measures.
2. Looser at long measures.
3. Contrast between body and headings.
Common failure modes include:
- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.
> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst
### Review checklist
- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread
### A note on formulas
Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$这份文档经排版引擎处理后,会生成结构化的VDTDocument,它的各页把上述每个块都存为带类型的条目。块如何变成几何形状,见架构一页。
#排版食谱中的示例
用到本页内容的食谱,每道列在最贴切的小节下。每道食谱都把页面和完整脚本并排展示。












