跳到主要内容
食谱编号92

排版食谱 · 第5章 · 图书结构

引用指向页码的产品手册

一本自行车用户手册,交叉引用写成“see section 3.2 on page 3”,前后互指,节号和页码都取自排版结果。

本页内容
输出
Canvas · PDF
难度
中级
Postext
已用Postext 1.65.0测试
需要≥ 1.28.0 · postext-pdf ≥ 1.28.0
许可证
更新于2026年10月11日
代码MIT · 文本CC BY 4.0
  • 英文样例:尚无中文版本
  • 成品尺寸148 × 210 mm
  • 1栏
  • Archivo 9.3/13
  • Archivo Narrow
  • 4页
  • 难度
  • Postext 1.57.1
  • 排版用时64 ms
  • 131行代码

简单来说

一本旅行自行车的简短用户手册。正文让你去看另一节时,会给出那一节的编号和所在页码,两者都可以点击。

成品一览

一辆虚构的旅行自行车Ardena T3的用户手册:四页A5,正文用Archivo,首页上半部是印着型号的藏青色色带。手册不会按顺序读,所以每条依赖其他内容的说明都写明位置:see section 3.2 on page 3。作者给标题、段落或步骤里的短语起一个标识符,在需要指过去的地方写:ref;Postext印出编号、标题或页码,并做成链接。封面上的目录也是这样写的,所以移动一节,或者翻译后重新排版,都不会留下过时的数字。

这道食谱解答

  • 怎样引用某一节及其所在页码,并在书变动时保持正确?

简短回答

script.js · 第28–38行在完整代码中
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };

用料

类型
Archivo, Archivo Narrow(SIL OFL 1.1)
素材
无:所有图片都用代码绘制

做法

#1 · 给要指向的地方起名

代码就是上面的简短回答。标题用Pandoc的标识符写法,### Checking pad wear {#sec-pad-wear};胎压警告以:anchor{#warn-pressure}开头,这是一个不可见的标记;装前轮的最后一步是[close the lever so that it points backwards]{#step-close-lever},文字保留并获得名字;标注框以:::callout{#box-wet type="note" title="Wet weather"}开头。引用这一步会印出它的文字,引用标注框会印出框的标题。

#2 · 同一个目标,四种叫法

:ref{id="sec-pad-wear"}用crossRefs.section的词印出section 3.2;style=page用crossRefs.page的词印出page 3;style=title印出Checking pad wear;style=pageNumber只印数字3。封面目录把单独的编号、标题和单独的页码组合起来,读起来就是一份目录。西班牙文版里同样的引用印成apartado 3.2和página 3,因为模板跟随该版的语言。

#3 · 页码自行稳定

页码要等手册排完才知道。引擎先排一遍,读出每个目标落在哪一页,再重排,直到没有引用再变化,和填写目录用的是同一个循环。译文变长,或者把某节移到前面,页码就会变,引用随之更新,无论向前还是向后指。

#4 · 编号来自第2级计数器

script.js · 第42–47行在完整代码中
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };

手册只有一个1级标题,即封面上的型号,所以各节从第2级开始编号:{2}得到1到5,{2}.{3}得到1.1、1.2。

#5 · 封面就是这个标题的章首

script.js · 第51–73行在完整代码中
const BAND = 104; // mm from the trim's top
const label = { fontFamily: DISPLAY, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.6), align: 'left' };
const cover = {
  enabled: true,
  minHeight: mm(BAND - PAGE.top + 8), // the contents start 8 mm under the band
  slot: { elements: [
    { kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
      placement: { ...at('page', 'top-left'), size: { width: 'fill', height: mm(BAND) } } },
    { kind: 'box', id: 'stripe', style: { backgroundColor: col('orange') },
      placement: { ...at('page', 'top-left', 0, BAND), size: { width: 'fill', height: mm(2.5) } } },
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...label, fontSize: pt(9),
      color: col('tint'), placement: at('container', 'top-left', 0, 6) },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 700,
      fontSize: pt(58), lineHeight: 1, color: col('paper'), align: 'left',
      placement: at('container', 'top-left', -1, 30) },
    { kind: 'text', id: 'subtitle', content: '{attr.subtitle}', fontFamily: TEXT,
      fontSize: pt(11), color: col('paper'), align: 'left',
      placement: at('container', 'top-left', 0, 55) },
    { kind: 'text', id: 'edition', content: '{attr.edition}', ...label, fontSize: pt(7.5),
      color: col('tint'), placement: at('container', 'top-left', 0, 74) },
  ] },
};

色带高104 mm,占半页,下缘一条橙色细带。眉题、副标题和版次都是标题属性,所以西班牙文版在自己的正文里改写它们。

script.js · 第13–20行在完整代码中
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));

完整食谱

沙盒
// ═══ Postext Cookbook · Nº 092 · A manual whose references point to pages ══════════
// https://postext.dev/en/cookbook/manual-see-page-references
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Archivo, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocumentWithFonts, renderPageToCanvas } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'manual-see-page-references';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a navy cover band and one signal orange for numbers and references
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Archivo', DISPLAY = 'Archivo Narrow';
const PAGE = { w: 148, h: 210, top: 20, bottom: 20, inner: 18, outer: 15 }; // mm: A5, mirrored
const LEAD = 13; // pt
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });

// #region answer: the words a reference prints, and references that are links
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };
// #endregion

// #region numbers: sections 1–5 and 1.1, 1.2… under the one level-1 heading
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };
// #endregion

组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)

变化

#引用里写成“p.”

页码引用很多的参考书用缩写可以省地方。

-  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
+  page: t({ en: 'p. {n}', es: 'pág. {n}' }),

#引用保持黑色

当页面上满是引用时,让它们用正文颜色加粗;在PDF和屏幕上它们仍是链接。

-const references = { referenceColor: col('orange'), referenceBold: true };
+const references = { referenceColor: col('ink'), referenceBold: true };

常见问题

  • 不带样式地引用:anchor会印出页码,因为不可见的锚点没有自己的文字。需要引用原文时,用[文字]{#id}。
  • 标识符在全书中必须唯一。引用指向第一个{#sec-brakes},沙盒的检查面板会把第二个列为duplicateAnchor。

致谢

文本
原创文字, CC BY 4.0
字体
Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
沙盒PDF