简单来说
一本讲蜡烛的著名科普讲座小册子。示例演示怎样把注释集中放到末尾,单独占一页并分两栏,而不是放在每页底部。
成品一览
这是Michael Faraday《The Chemical History of a Candle》的第一讲,排成一本小开本普及本,页面尺寸为156 × 234 mm。讲座以一片烟灰色区域开篇,一支点燃的蜡烛立在它的下缘,这是一张由扩散模型生成的照片,黑色背景与烟灰色区域相融;正文用Libre Bodoni排成一栏,两端对齐。在一般书里放脚注的地方,深橙色的小号上标数字把读者引向讲座末尾。注释单独成页,页首是一条烟灰色色带,里面的蜡烛已经熄灭;注释用8.2 pt分两栏齐左排出,每个粗体编号悬挂在缩进里。六条注释中有三条出自William Crookes,取自他1861年版本的1908年重印本;另外三条是新写的,署名Ed.。两栏结束在同一行,版权信息排在第二栏末尾。
这道食谱解答
- 脚注怎么做?
- 怎样排参考文献或术语表(悬挂缩进、较小字号)?
- 不用完整的数学公式,怎样写上标、下标和化学式?
简短回答
// Use: buildDocument({ markdown: endnotes(markdown) }, config()), with a 'note' paragraph style.
// [^label] in the text → **^n^**, numbered by first citation; bold, so it takes bodyText.boldColor.
// The [^label]: definitions (one line each) print where the first stood, a 'note' paragraph each:
// '**n** text', never '1. text', which would open a numbered list (gotcha: digit-period-list).
function endnotes(markdown, style = 'note') {
const notes = new Map(); // label → text
const HOLE = '\u0000'; // marks where a definition stood: the first becomes the notes
const text = markdown.replace(/^\[\^([^\]\s]+)\]:[ \t]*(.+)\n?/gm,
(_, label, note) => { notes.set(label, note.trim()); return HOLE; });
const cited = []; // labels in order of first citation
const number = (label) => {
if (!notes.has(label)) throw new Error(`The note [^${label}] has no definition`);
if (!cited.includes(label)) cited.push(label);
return cited.indexOf(label) + 1;
};
// Markers side by side share one superscript, [^a][^b] → **^1,2^**, never 12 raised (note 12).
// A word joiner (U+2060, no width) opens each one: after an italic, '*Royal George*' and the
// bold's ** would make '***', which the parser reads as a bold run, and print the asterisks.
const marked = text.replace(/(?:\[\^[^\]\s]+\])+/g, (run) => {
const numbers = [...run.matchAll(/\[\^([^\]\s]+)\]/g)].map(([, label]) => number(label));
return `**^${numbers.join(',')}^**`;
});
const unused = [...notes.keys()].filter((label) => !cited.includes(label));
if (unused.length) console.warn(`Notes never cited: ${unused.join(', ')}`);
const entries = cited.map((label, i) => `**${i + 1}** ${notes.get(label)}`);
const section = `:::paragraphs{style="${style}"}\n${entries.join('\n\n')}\n:::\n`;
return marked.replace(HOLE, () => section).replaceAll(HOLE, ''); // () =>: '$&' stays text
}
用料
- 功能
- 上标与下标参考文献与术语表分节版式标题样式各栏齐底栏间线段落样式转义与字面字符粗体、斜体及其颜色决定图位置的引用编号题注自定义资源类型题注样式设计过的章首页页面设计中的图片标题属性书眉与页码对称页边距语义调色板
- 类型
- Libre Bodoni, Besley, Archivo Narrow(SIL OFL 1.1)
- 素材
candle-640.jpgsnuffed-600.jpg- The lit candle on the lecture’s opener, a photograph (Generated With Diffusion Models, 原创)
- The snuffed candle on the notes’ band, a photograph (Generated With Diffusion Models, 原创)
- Figure 1, the flame as seen and in section, drawn in code in the page’s palette (Ignacio Ferro, CC BY 4.0)
做法
#1 · 在排版之前把脚注改成尾注
预处理程序就是上面的简短回答。Postext自己就能排[^1]注释(脚注),位置在引用它的栏底,或者设placement: 'chapterEnd'时,放在本章最后一个块之后。无论哪种方式,注释都留在本章的栏里,用正文字体,排在一条短线下。这个版本要给注释一个标题、一条色带和一个双栏页面,而标题样式只能作用于写在Markdown里的标题。所以pen在调用buildDocument之前改写Markdown,引擎根本不会看到[^1]。它按正文首次引用的顺序给标记编号,并按这个顺序把所有定义放在第一个定义所在的位置,排在## Notes之下。每条注释以**1**开头,因为1. 会开始一个有序列表。每个标记以一个词连接符(U+2060)开头;没有它,*Royal George*之后那个标记的**会与斜体的闭合星号连成***,星号就会印出来。
#2 · 把粗体留给标记
const markers = { boldColor: col('ember'), // **^n^**: a superscript at 58 % of the text size
referenceBold: false }; // [Fig. 1] follows the bold colour, set roman
预处理程序把每个标记写成**^n^**。插入符号把数字设为正文字号的58 %,并上移其三分之一(行内格式);粗体则让它取bodyText.boldColor,这个颜色空着没用,因为Faraday从不用粗体。5.8 pt的数字需要与纸面达到4.5:1的对比度,而火焰橙只有2.6:1,所以标记改用更深的余烬色。第17页上的引用[Fig. 1]印成同一种颜色,但用正体,因为referenceColor默认取粗体颜色,而referenceBold: false去掉了粗体。
#3 · 注释用小一号的字,编号放在悬挂缩进里
const NOTE = 8.2; // pt: the notes' size, about four fifths of the text
// The hang is a bold number and an en space, measured in the notes' face once the fonts are in:
// a bold 5 matches 2, 3 and 6 within 0.02 em (the 4 is 0.05 em wider, the 1 0.14 em narrower).
function hang(label = '5') { // from ten notes on, pass the widest label: hang('10')
const ctx = new OffscreenCanvas(1, 1).getContext('2d');
const width = (w, s) => { ctx.font = `${w} 100px "${TEXT}"`; return ctx.measureText(s).width; };
return em((width(700, label) + width(400, ' ')) / 100);
}
// Ragged, as justifying would stretch the en space after each number.
const noteStyles = () => [{ id: 'note', fontSize: pt(NOTE), lineHeight: pt(NOTE * 1.3),
textAlign: 'left', hangingIndent: hang() },
// 22 pt above the colophon is copy-fitted: its last line and the first column's share a line.
{ id: 'colophon', fontFamily: LABEL, fontSize: pt(7), lineHeight: pt(9.2), color: col('muted'),
textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(22) },
];
注释为8.2 pt,行距10.7 pt,约为正文字号的五分之四。字体加载后,pen用Libre Bodoni测量这一样式的hangingIndent:一个粗体5加一个半角空格共1.12 em,所以每条注释的第一个词与其转行对齐(段落样式)。编号放到悬挂缩进里之后,注释之间就不需要空行。注释齐左排,因为两端对齐会拉宽那个半角空格,而在55 mm的栏里两端对齐8.2 pt的字会排得很松。波浪号设下标,就像插入符号设上标一样,例如注释4中的C~25~H~52~和注释5中的H~2~O。
#4 · 给注释一个双栏页面
const BAND = 82; // mm from the trim's top: level with the foot of Figure 1 across the spread
// The band sets the reserve too, but the first grid line clear of it lies 3 mm under the soot:
const BAND_GAP = 5; // mm more of minHeight moves the notes down a line
const notesSection = { id: 'notes', // an opener page: the drop folio, no running heads
breakBefore: { enabled: true, parity: 'any' }, span: 'page', // the next page, either side
layout: { layoutType: 'double', gutterWidth: mm(6), // two columns of about 40 characters
columnRule: { enabled: true, color: col('rule') } }, // and a hairline between them
advancedDesign: { enabled: true, minHeight: mm(BAND - TOP + BAND_GAP), slot: { elements: [
soot(BAND), art('snuffed', 32, 64, BAND, 12), series,
text('kicker', '{attr.kicker}', LABEL, 9.5, 'flame', at('container', 'top-left', 0, 16),
caps(9.5)),
text('title', '{titleText}', DISPLAY, 52, 'wax', below('kicker', 0.5, 80), display),
text('intro', '{attr.intro}', LABEL, 8.4, 'rule', below('title', 2.5, 92),
{ lineHeight: 1.3 }),
] } } };
标题## Notes {style="notes" …}开始一个部分,这一部分的页面采用该样式的版式和版面设计。parity: 'any'让它从下一页开始,不论奇偶;span: 'page'让色带横跨两栏,一直伸到裁切边,第二栏从色带下方开始(标题样式)。预留高度由色带决定,但离开色带后的第一条网格线距烟灰色区域只有3 mm,所以BAND_GAP给minHeight加上5 mm,注释从低一行的位置开始。栏间细线是样式自身layout里的columnRule,所以只有注释的页面会画出它。各栏齐底默认开启,它会裁切末页,让两栏结束在同一行(各栏齐底)。
#5 · 讲座以一片烟灰色区域开篇
const FIELD = 112; // mm from the trim's top
// The field reaches below the heading, so it sets the reserve (gotcha: opener-reserves-anchored);
// the H1's default bottom margin (0.5 em of 18 pt) rides on it: the text starts a grid line lower.
const opener = { enabled: true,
slot: { elements: [soot(FIELD), art('candle', 40, 100, FIELD, 10), series,
text('kicker', '{attr.kicker}', LABEL, 9.5, 'flame', below('series', 17, 60), caps(9.5)),
text('title', '{titleText}', DISPLAY, 48, 'wax', below('kicker', 1.5, 96), display),
// 86 mm wide, so the subtitle breaks after a dash, never before one
text('subtitle', '{attr.subtitle}', DISPLAY, 11.5, 'rule', below('title', 3.5, 86),
{ fontWeight: 500, italic: true, lineHeight: 1.3 }),
text('byline', '{attr.byline}', LABEL, 7.6, 'rule', below('subtitle', 7, 84), caps(7.6)),
] } };
这片区域是一个锚定在页面上的框,蜡烛是一个装着JPEG的图像元素,立在框的下缘。讲座只有一栏,留在栏内的版面设计照样画在各元素锚定的位置,所以这片区域从裁切边起,越过天头和左右页边。眉题、副标题和作者署名来自标题行# A Candle {kicker="Lecture I" subtitle="…" byline="…"},所以第二讲不需要新代码。这片区域延伸到标题下方,因此由它决定预留高度。标题默认的0.5 em下外边距加在上面,正文从离开烟灰色区域后的第一行再往下一个网格行开始。副标题宽86 mm,这样它只在破折号后折行,不会在破折号前折行。
#6 · 烟灰上用火焰橙,纸上用余烬色
const palette = {
ink: '#1f1c19', paper: '#fffdf8', // text and the soot of the fields; a warm white page
flame: '#e08a1e', ember: '#a9560c', // kickers on soot (6:1); markers and numbers (5.1:1)
wax: '#f6efe1', rule: '#d4c6ad', // type on soot; hairlines and small type on soot (10:1)
muted: '#6d6356', blue: '#4f7cae', // running heads, colophon (5.8:1); a flame's blue foot
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the ember, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.ember })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
火焰橙在烟灰色上的对比度为6:1,在纸上只有2.6:1。它用于深色色带上的眉题和Figure 1;纸上所有用橙色印的小字(标记、注释编号、图的标签)都改用更深的余烬色,对比度为5.1:1。main-color指向余烬色,所以配置里没有重新设定的默认值会跟随设计,而不会印成蓝色。
完整食谱
// ═══ Postext Cookbook · Nº 020 · Endnotes on a page of their own, in two columns ═════
// https://postext.dev/en/cookbook/endnotes-instead-of-footnotes
// Code: MIT · Text: Faraday, ed. Crookes (PD) · Notes, figure: CC BY 4.0 · Photos: diffusion models
// Fonts: Libre Bodoni, Besley, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'endnotes-instead-of-footnotes';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: soot, wax and a flame; the ember is the flame dark enough for small type
const palette = {
ink: '#1f1c19', paper: '#fffdf8', // text and the soot of the fields; a warm white page
flame: '#e08a1e', ember: '#a9560c', // kickers on soot (6:1); markers and numbers (5.1:1)
wax: '#f6efe1', rule: '#d4c6ad', // type on soot; hairlines and small type on soot (10:1)
muted: '#6d6356', blue: '#4f7cae', // running heads, colophon (5.8:1); a flame's blue foot
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the ember, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.ember })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Libre Bodoni', DISPLAY = 'Besley', LABEL = 'Archivo Narrow'; // text; titles; labels
const TOP = 22, INNER = 18, OUTER = 22; // mm: margins, and a 116 mm measure of 74 characters
// #region answer: Markdown footnotes become raised markers and a Notes section
// Use: buildDocument({ markdown: endnotes(markdown) }, config()), with a 'note' paragraph style.
// [^label] in the text → **^n^**, numbered by first citation; bold, so it takes bodyText.boldColor.
// The [^label]: definitions (one line each) print where the first stood, a 'note' paragraph each:
// '**n** text', never '1. text', which would open a numbered list (gotcha: digit-period-list).
function endnotes(markdown, style = 'note') {
const notes = new Map(); // label → text
const HOLE = '\u0000'; // marks where a definition stood: the first becomes the notes
const text = markdown.replace(/^\[\^([^\]\s]+)\]:[ \t]*(.+)\n?/gm,
(_, label, note) => { notes.set(label, note.trim()); return HOLE; });
const cited = []; // labels in order of first citation
const number = (label) => {
if (!notes.has(label)) throw new Error(`The note [^${label}] has no definition`);
if (!cited.includes(label)) cited.push(label);
return cited.indexOf(label) + 1;
};
// Markers side by side share one superscript, [^a][^b] → **^1,2^**, never 12 raised (note 12).
// A word joiner (U+2060, no width) opens each one: after an italic, '*Royal George*' and the
// bold's ** would make '***', which the parser reads as a bold run, and print the asterisks.
const marked = text.replace(/(?:\[\^[^\]\s]+\])+/g, (run) => {
const numbers = [...run.matchAll(/\[\^([^\]\s]+)\]/g)].map(([, label]) => number(label));
组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)
变化
#让Postext排注释
去掉endnotes()和## Notes标题,在各条定义之间加空行(引擎把一条定义读到下一个空行为止),并在配置里加上footnotes: { placement: 'chapterEnd' }。引擎会给标记编号,把注释排在讲座末尾、版权信息之后,仍在那一栏里;排在引用栏底部的脚注讲的是如何设置引擎所排注释的样式。
#用墨色印标记
如果正文自己用粗体表示强调,就把标记印成墨色,因为boldColor会同时给标记和每个粗体词上色。
-const markers = { boldColor: col('ember'), // **^n^**:上标,为正文字号的58 %
+const markers = { boldColor: col('ink'), // **^n^**:上标,为正文字号的58 %#让注释各栏不齐底
关闭末页的各栏齐底,第一栏会先排满到栏底,第二栏才开始。
- headings: { fontFamily: DISPLAY, color: col('ink'), levels: [
+ headings: { fontFamily: DISPLAY, color: col('ink'), balancing: { trailing: false }, levels: [常见问题
易错点
'top'浮动体默认排在引用页的下一页,除非允许它置于引用页顶
默认情况下浮动体不会排在自己的引用之前,所以在第N页引用的整页宽'top'浮动体会出现在第N+1页的顶部。在资源或其类型的defaultPlacement上设置placement.citingPage: true(或者对全书设置layout.floatsAtCitingPage,自postext 1.25起),它就改为置于第N页顶部,引用处之上的文字移到它下方,前提是它不超过layout.maxTopFraction且引用行仍留在该页。它不会置于章首页或强制分页之后的页面顶部:那时仍排在下一页,而'auto'或'bottom'可以占用引用页的底部。 图的放置 →
易错点
章首页预留的高度一直到最低的页面锚定元素
高级设计的章首页会预留到其最低元素为止的高度,标题下方锚定在页面或出血上的元素也算在内,所以页脚处的装饰会把正文推到下一页。给这样的元素设reserve: false(从postext 1.5起):它绘制在锚定的位置,不预留任何空间。跟随区段本身的元素(锚定在区段底边,或高度为'fill')从不决定区段的高度。 设计过的章首页 →
易错点
SVG插图中不要用<marker>或滤镜(会退回位图)
SVG图只有在不含<marker>、滤镜和蒙版时,才能在PDF中保持矢量;否则会退回位图,而且层层嵌套的滤镜可能让它在Chrome中变成空白。箭头用路径来画。 作为资源的图和表 →
致谢
- 文本
- The Chemical History of a Candle, Lecture I (abridged), and William Crookes’s notes to it, from the Chatto & Windus impression of 1908 · Michael Faraday; William Crookes · 公有领域
- The notes signed Ed., the colophon and the drawings · Ignacio Ferro · CC BY 4.0
- 图片
- The lit candle on the lecture’s opener, a photograph · Generated With Diffusion Models · 原创
- The snuffed candle on the notes’ band, a photograph · Generated With Diffusion Models · 原创
- Figure 1, the flame as seen and in section, drawn in code in the page’s palette · Ignacio Ferro · CC BY 4.0
- 字体
- Libre Bodoni (SIL OFL 1.1) · Besley (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)


