انتقل إلى المحتوى الرئيسي
الوصفة رقم 94

دليل الوصفات · الفصل 5 · بنية الكتاب

كتاب تقني تعبر إحالاته بين الفصول

دليل طاقة شمسية من ثلاثة فصول يكتب نصه @fig:sun و@tbl:loads و@sec:array-size، وتطبع buildBundle كل رقم وصفحة عبر الفصول.

في هذه الصفحة
المُخرَج
Canvas · PDF
المستوى
متقدم
Postext
اختُبرت مع Postext 1.65.0
تتطلب ≥ 1.28.0 · postext-pdf ≥ 1.28.0
الترخيص
حُدّثت في 11 أكتوبر 2026
الشيفرة MIT · النص CC BY 4.0
  • نموذج باللغة الإنجليزية: لا توجد طبعة عربية بعد
  • مقاس القص 178 × 233 مم
  • عمود واحد
  • IBM Plex Serif 9.6/13.8
  • IBM Plex Mono
  • IBM Plex Sans Condensed
  • 9 صفحات
  • المستوى
  • Postext 1.57.1
  • أُخرجت في 134 ms
  • أسطر الشيفرة: 246

باختصار

كتيّب قصير عن تحديد مقاس الألواح الشمسية والبطاريات لكوخ. حين يشير الفصل 3 إلى جدول في الفصل 1، أو يشير الفصل 1 إلى قسم لاحق في الفصل 2، يُطبع الرقم والصفحة الصحيحان، ويكونان روابط.

ما الذي ستنضده

كتيّب تقني قصير، Power for a Cabin، منضّد بخط IBM Plex على صفحة مقاسها 178 × 233 مم: غلاف عليه مسارات الشمس مرسومة بالشيفرة، وصفحة محتويات، وثلاثة فصول تحت شريط أزرق ليلي. يحدد الكتاب مقاس منظومة شمسية صغيرة، فكل فصل يستند إلى الآخرين. يستشهد الفصل 3 بجدول الأحمال في الفصل 1 وبمخطط ساعات الشمس في الفصل 2؛ ويرسل الفصل 1 القارئ إلى القسم 2.3 اللاحق ويذكر صفحته. يكتب المؤلف @tbl:loads و@sec:array-size، كما يقرؤها pandoc-crossref، في أربعة ملفات Markdown منفصلة. وتخرجها buildBundle كتابًا واحدًا، فتطبع كل إحالة الرقم الذي أخذه هدفها في فصله، والصفحة التي وقع عليها، ورابطًا إليه.

تجيب هذه الوصفة عن

  • كيف أحيل إلى شكل أو جدول أو قسم في فصل آخر، على طريقة pandoc-crossref، وأبقي الأرقام صحيحة؟
  • كيف أحيل إلى قسم والصفحة التي يقع فيها، وأبقي الاثنين صحيحين حين يتغير الكتاب؟

الجواب المختصر

script.js · الأسطر 44–61في الشيفرة الكاملة
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

المكونات

الخطوط
IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
الأصول
لا شيء: كل صورة مرسومة بالشيفرة

طريقة التحضير

#1 · سمِّ كل هدف مرة واحدة، للكتاب كله

الشيفرة في الجواب المختصر أعلاه. تأخذ العناوين معرّف Pandoc مع بادئته، ## Sizing the array {#sec:array-size}. الأشكال والجداول موارد مصرَّح بها في السكربت، ومعرّفاتها مكتوبة بالطريقة نفسها، fig:sun وtbl:loads، فيكتب النص @fig:sun سواء كان الشكل على بعد فقرتين أو قبل فصلين. ويجب أن يكون المعرّف فريدًا في الكتاب كله، لا في فصله وحده.

#2 · أخرج الفصول كتابًا واحدًا

script.js · الأسطر 44–61في الشيفرة الكاملة
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

تنقل buildBundle عدّادات الأشكال والجداول من فصل إلى فصل، فيكون أول جدول في الفصل 3 هو 3.1 وتظل @tbl:loads في الفصل 3 تطبع table 1.1. والفصل الذي يذكر نصه عنوانًا لا يحويه يُخرَج مع مخطط الكتاب كله، ثم يُعاد إخراجه (ثلاث جولات على الأكثر) حتى تتوقف صفحات ذلك المخطط عن التحرك. بهذا يستطيع الفصل 1 أن يطبع section 2.1 … p. 6 قبل أن يوجد الفصل 2 على الورق.

#3 · اختر الكلمات التي تطبعها الإحالة

يضبط crossRefs الكلمات chapter وsection وp. (وفي الإسبانية capítulo وapartado وpág.). وتطبع إحالة الشكل أو الجدول shortLabel الخاص بنوعه، هنا بحروف صغيرة كما يضعها pandoc-crossref، fig. 2.1 وtable 1.1. والحرف الكبير في البادئة، @Tbl:loads أو @Sec:array، يجعل أول حرف من التسمية كبيرًا في بداية الجملة، و[-@tbl:losses] يطبع الرقم مجردًا في tables 2.1 and 3.1.

#4 · أحِل إلى الأقسام اللاحقة، وإلى الأشكال السابقة

يُرقَّم الشكل أو الجدول، ويُعوَّم، حيث يُستشهد به أول مرة. لو وُضعت @fig:soc في الفصل 1 لجعلته الشكل 1.2 ووضعته في الفصل 1. لذا يحيل الفصل 1 إلى @sec:autonomy اللاحق، ويُستشهد بالأشكال والجداول أول مرة في فصلها؛ وكل فصل بعد ذلك يحيل إليها بحرية. والصفحة ترافق القسم، :ref{id="sec:sun-hours" style=page}: إحالة المورد تطبع تسميته ورقمه، ولا تطبع صفحته أبدًا.

#5 · صفحات الافتتاح والغلاف من الشريط نفسه

script.js · الأسطر 65–85في الشيفرة الكاملة
const BAND = 52; // mm from the trim's top
const opener = { enabled: true, minHeight: mm(54), slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(BAND + 3) } } },
  { kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...caps(8.5),
    color: col('sun'), placement: at('container', 'top-left', 0, 2) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(30), lineHeight: 1.05, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#kicker', 'below', 0, 3), size: { width: mm(MEASURE - 26) } } },
  { kind: 'text', id: 'number', content: '{chapterNumber}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(84), lineHeight: 1, color: col('sun'), align: 'right',
    placement: { ...at('container', 'top-right', 0, -6), size: { width: mm(40) } } },
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
    fontSize: pt(11), lineHeight: 1.38, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { ...at('container', 'top-left', 0, BAND - MARGIN.top + 8),
      size: { width: mm(MEASURE - 10) } } },
] } };
// The contents page wears the same band, with the book's subtitle as its kicker.
const contentsOpener = { ...opener, minHeight: mm(BAND - MARGIN.top + 4), slot: { elements:
  opener.slot.elements.filter((e) => ['band', 'kicker', 'title'].includes(e.id))
    .map((e) => (e.id === 'kicker' ? { ...e, content: '{subtitle}' } : e)) } };

يمتد الشريط 55 مم من حدّ القص العلوي في كل فصل وفي صفحة المحتويات، وهي تعيد استعمال العناصر نفسها؛ رقم الفصل هو {chapterNumber}، والمقدمة سمة في العنوان.

script.js · الأسطر 89–109في الشيفرة الكاملة
const COVER_BAND = 168; // mm
const cover = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(COVER_BAND) } } },
  { kind: 'image', id: 'art', resourceId: 'cover',
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill' } } },
  // Stacked upwards from the subtitle, so a title of one line or two keeps its distance.
  { kind: 'text', id: 'subtitle', content: '{subtitle}', fontFamily: SERIF, italic: true,
    fontSize: pt(14), color: col('tint'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND - 22) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(52), lineHeight: 1, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#subtitle', 'above', 0, -4), size: { width: mm(140) } } },
  { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...caps(8.5), color: col('sun'),
    placement: at('#title', 'above', 0, -4) },
  { kind: 'text', id: 'author', content: '{author}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(13), color: col('ink'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND + 14) },
  { kind: 'text', id: 'edition', content: '{attr.edition}', ...caps(7.5), color: col('muted'),
    placement: at('#author', 'below', 0, 2.5) },
] } };

الوصفة كاملة

Sandbox
// ═══ Postext Cookbook · Nº 094 · A technical book whose references cross chapters ═══
// https://postext.dev/en/cookbook/technical-book-crossref-chapters
// Code: MIT · Text: original (CC BY 4.0) · Charts: generated in code (CC BY 4.0)
// Fonts: IBM Plex Serif, Sans Condensed and Mono (SIL OFL 1.1) · Needs postext ≥ 1.28.0
// A small handbook in four Markdown documents. The text writes @fig:sun, @tbl:loads and
// @sec:array-size the way pandoc-crossref reads them, and buildBundle resolves each one to
// the right number, title or page wherever in the book its target lies.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
  defaultResourceTypes, parseTSV, setAlignment, inlineSvgFonts,
} 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 = 'technical-book-crossref-chapters';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a night-blue band, one burnt-orange accent, an amber for the charts
const palette = {
  ink: '#1c1f24', // text: a cool near-black
  night: '#1f3247', // openers, the cover, table heads
  accent: '#a8471a', // numbers, kickers, references (5.6:1 on paper)
  sun: '#e9a33a', // the charts and the cover only, never text on paper
  tint: '#f5ede3', // daylight in the charts
  rule: '#cfc7bc', // hairlines
  muted: '#5e636a', // running heads, colophon, chart labels
  paper: '#ffffff',
};
// Each colour names its palette entry and carries its hex.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.accent })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const SERIF = 'IBM Plex Serif', COND = 'IBM Plex Sans Condensed', MONO = 'IBM Plex Mono';
const TRIM = { w: 178, h: 233 }; // mm: a technical-book trim
const MARGIN = { top: 22, bottom: 22, inner: 20, outer: 32 }; // a 126 mm measure
const LEAD = 13.8; // pt: the body leading
const MEASURE = TRIM.w - MARGIN.inner - MARGIN.outer;
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const caps = (size, extra = {}) => ({ fontFamily: MONO, fontSize: pt(size), fontWeight: 600,
  letterSpacing: pt(size * 0.14), textTransform: 'uppercase', align: 'left', ...extra });

// #region answer: one set of identifiers for the whole book, resolved across chapters
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.

يعمل ملف script.js المجمّع كما هو: الصقه في سكربت الوحدة (module) لأي صفحة، أو افتح الوصفة على CodePen. مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)

تنويعات

#اطبع «Figure 2.1» في النص

الكتاب الذي يكتب إحالاته كاملة يستخدم الاسم الكامل للنوع بدلًا من التسمية المختصرة.

-  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
-    : t({ en: 'fig.', es: 'figura' }),
+  shortLabel: type.id === 'table' ? t({ en: 'Table', es: 'Tabla' })
+    : t({ en: 'Figure', es: 'Figura' }),

#رقّم الأقسام بعلامة الفقرة

-  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
+  section: '§ {n}',

أخطاء شائعة

خطأ شائع

يُرقَّم الشكل ويُوضع حيث يُحال إليه أول مرة

أول إحالة :ref أو @fig: إلى شكل أو جدول تعطيه رقمه وموضعه، فالإحالة في فصل سابق تجرّه إليه. أحِل إلى الأمام إلى القسم الذي يحتويه، ولا تُحِل إلى الشكل نفسه إلا بعد أن يُوضع. الإحالات →

  • الإحالة إلى معرّف لا يضبطه أي فصل تطبع ?. راجع المعرّفات بعد إعادة تسمية عنوان في فصل: الإحالات إليه موجودة في الفصول الأخرى.
  • إخراج الفصول واحدًا واحدًا بـbuildDocument يُفقد العدّادات ومخطط الكتاب معًا: كل فصل يعيد ترقيم أشكاله من 1، والإحالة إلى فصل آخر تطبع ?. استخدم buildBundle، أو اربط continuation ومرّر outline بنفسك.
  • ليس للمعادلات ترقيم خاص بها في Postext، لذا لا يجد @eq: إلا مرساة تضعها أنت ويطبع نصها؛ وهذا الكتاب يكتب صيغتيه بلا أرقام.
  • عنوان القسم الذي يفتتح صفحة، أو يقع تحت جدول في رأس الصفحة مثل القسم 3.3 في الصفحة 9، يفقد افتراضيًا المسافة التي فوقه كلها، فيضع الانضباط على الشبكة تحت العنوان جزء السطر الذي يحتاج إليه، ويبتعد نصه عنه أكثر مما يبتعد عن العناوين في وسط الصفحة. يُبقي headings.columnHeadSpace: 'remainder' هذا الجزء من السطر فوق العنوان (العناوين). وهو يناسب كتابًا بعمود واحد، حيث لا عمود مجاور يُظهر أن العنوان يبدأ أدنى قليلًا.

الحقوق

الوصفة
Ignacio Ferro
النص
نص أصلي, CC BY 4.0
الخطوط
IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
الشيفرة
MIT، مثل Postext
SandboxPDF