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

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

كتاب واحد من فصول منفصلة

ينضّد buildBundle خمسة ملفات Markdown كتابًا واحدًا: يبدأ كل فصل على صفحة فردية، وتتواصل أرقام الصفحات والفصول والأشكال من ملف إلى آخر.

في هذه الصفحة
المُخرَج
Canvas · PDF
المستوى
متقدم
Postext
اختُبرت مع Postext 1.65.0
تتطلب ≥ 1.25.0 · postext-pdf ≥ 1.25.0
الترخيص
حُدّثت في 10 أكتوبر 2026
الشيفرة MIT · النص CC BY 4.0
  • نموذج باللغة الإنجليزية: لا توجد طبعة عربية بعد
  • مقاس القص 150 × 200 مم
  • عمود واحد
  • Andada Pro 10.4/14.2
  • Figtree
  • Rozha One
  • 11 صفحة
  • المستوى
  • Postext 1.57.1
  • أُخرجت في 95 ms
  • أسطر الشيفرة: 229

باختصار

كتيّب قصير عن تربية النحل مكتوب في ملفات منفصلة، ملف لكل فصل. يجمعها Postext في كتاب واحد، وتتواصل أرقام الصفحات والفصول والصور من ملف إلى الذي يليه.

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

A Beekeeper’s Year كتيّب صغير في أربعة فصول، فصل لكل موسم. يبدأ بالخريف (Autumn)، لأن سنة النحّال تبدأ حين يُجنى آخر العسل. كل فصل ملف Markdown مستقل ليس فيه رقم صفحة ولا رقم فصل ولا رقم شكل. ينقل buildBundle هذه العدّادات من كل ملف إلى الذي يليه، وينضّد الفصول، ومعها ملف خامس للغلاف والمحتويات، كتابًا واحدًا من إحدى عشرة صفحة. يبدأ كل فصل على صفحة يمنى تحت ركن من أقراص الشمع عليه رقمه. أما صفحة المحتويات، وهي الصفحة الزوجية المقابلة لفصل Autumn، فتعكس صفحة الافتتاح هذه بعنوانها الملاصق للكعب، وتذكر رقم الصفحة التي يبدأ عليها كل فصل. وإطار حضنة واحد، مرسوم بالشيفرة، يظهر مرة في كل فصل بوصفه الأشكال من 1.1 إلى 4.1. وتبقى الصفحة 6 بيضاء لأن فصل Winter يملأ صفحة واحدة ولا بد أن يبدأ Spring على صفحة فردية.

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

  • كيف أُخرج كتابًا من عدة فصول بحيث يتواصل ترقيم الصفحات والأشكال والفصول عبر الفصول؟
  • كيف أضيف جدول محتويات يحدّث نفسه (نقاط توجيه، أرقام صفحات، مؤلفون، صفوف الأجزاء)؟
  • كيف أفرض فاصل صفحة أو عمود، وأبدأ كل فصل على صفحة يمنى؟
  • كيف أخفي الترويسات في صفحات الافتتاح والصفحات الفارغة، أو ألوّن صفحة زوجية فارغة بلون الجزء؟

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

script.js · الأسطر 71–102في الشيفرة الكاملة
// buildBundle lays the documents out in order with one config and carries state from each to
// the next: the pages already set (so parity goes on), the folio, the chapter and figure counts.
const book = () => buildBundle({ chapters, config: config(), resources });
const config = () => ({
  headings: { ...display, levels: [
    // Every chapter opens on a recto: after a chapter that ends on one, the next document
    // starts with a blank verso of its own.
    { level: 1, breakBefore: { enabled: true, parity: 'odd' },
      // '{1}' puts the number in the PDF bookmarks ('1 Autumn'); the contents and
      // {chapterNumber} count the chapters in order either way.
      numberingTemplate: '{1}', advancedDesign: opener,
      span: 'page' }, // in the column a design stops at the column's foot: the cover would too
    subhead,
  ] },
  // The cover and the contents are headings that take no number, no contents entry and no
  // running heads, so Autumn is still chapter 1. Both inherit span 'page', which starts
  // each on a page of its own, and parity 'odd', which the contents turn off: it would
  // leave page 2 blank (gotcha: style-inherits-break).
  headingStyles: [
    { id: 'cover', numbered: false, toc: false, advancedDesign: cover, ...bare },
    { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false },
      advancedDesign: contentsOpener, ...bare },
  ],
  // :::toc in the first document lists the whole book with the folio each chapter lands on:
  // buildBundle lays the book out again (three passes at most) until those folios settle.
  toc: contents,
  // The locale picks the hyphenation patterns and names the figures Figure or Figura. They
  // number {h1}.{n}, and the counters carry on from document to document (Winter's is 2.1).
  locale: t({ en: 'en-us', es: 'es' }),
  colorPalette, page, layout: { layoutType: 'single' }, bodyText, captionStyle, calloutStyles,
  header, footer, // the look: above, and in the regions below
});

المكونات

الخطوط
Andada Pro, Rozha One, Figtree (SIL OFL 1.1)
الأصول
لا شيء: كل صورة مرسومة بالشيفرة

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

#1 · ملف لكل فصل

script.js · الأسطر 337–338في الشيفرة الكاملة
// Nothing in a chapter says where it lands: buildBundle works that out from the order.
const chapters = [front, autumn, winter, spring, summer].map((markdown) => ({ markdown }));

كل موسم مستند قائم بذاته، فتستطيع إعادة كتابة فصل دون أن تفتح الفصول الأخرى. في المستند الأول البيانات التمهيدية (frontmatter) والغلاف والمحتويات. وبياناته الوصفية هي بيانات الكتاب: يطبعها {title} و{author} في كل فصل، ويأخذ ملف PDF العنوان والمؤلف منه.

#2 · قواعد تنتقل عبر المستندات

شيفرة هذه الخطوة هي الجواب المختصر أعلاه. يُخرج buildBundle المستندات بالترتيب بإعدادات مشتركة واحدة، ويمرّر إلى كل منها continuation مما سبقه: عدد الصفحات الفعلية المنضّدة حتى الآن، فتستمر الزوجية والفردية والهوامش المتناظرة وترويسات الصفحات الفردية والزوجية؛ ورقم الصفحة التالي؛ وعدّادات الفصول والأشكال. ومع parity: 'odd' يبدأ الفصل الذي يلي فصلًا انتهى على صفحة فردية بصفحة زوجية بيضاء، وهذه الصفحة البيضاء تنتمي إلى مستنده هو (الفصل قبل العنوان). الغلاف والمحتويات أنماط عناوين مع numbered: false، فيبقى Autumn الفصل 1. ويرث كلاهما span: 'page' من مستوى الفصل، فيوضع كل منهما على صفحة خاصة به دون :::pagebreak. ويُبطل نمط المحتويات الزوجية الموروثة، التي كانت ستترك الصفحة 2 بيضاء لولا ذلك.

#3 · محتويات الكتاب كله

script.js · الأسطر 215–228في الشيفرة الكاملة
const contents = {
  levels: [
    { level: 1, fontFamily: 'Rozha One', fontSize: pt(16), lineHeight: pt(18),
      numberFontFamily: 'Figtree', numberFontSize: pt(11), numberFontWeight: 700,
      numberColor: col('accent'), numberWidth: mm(7), numberGap: mm(4), marginTop: pt(8) },
    // Sections: 9.3 pt in the muted colour, indented 11 mm (number 7 + gap 4) to the titles.
    { level: 2, fontSize: pt(9.3), lineHeight: pt(13.5), indent: mm(11), color: col('muted') },
  ],
  pageNumber: { fontFamily: 'Figtree', fontSize: pt(8.5), fontWeight: 600, width: mm(7) },
  leader: { char: '. ', gap: mm(2) },
  // A second line under each chapter, from its {months="…"} heading attribute.
  subtitle: { enabled: true, attr: 'months', fontFamily: 'Andada Pro', fontSize: pt(9),
    color: col('muted') }, // italic by default
};

يقع :::toc في المستند الأول لكنه يسرد فصول الكتاب كله وأقسامه. يُخرج buildBundle الكتاب، ويجمع كل عنوان مع رقم الصفحة الذي ناله، ثم يُخرج الكتاب مرة أخرى بهذا المخطط حتى تكفّ الأرقام عن التحرك، في ثلاث جولات على الأكثر (جدول المحتويات). وتأتي الأشهر المكتوبة تحت كل عنوان من سمة على العنوان، {months="…"}، تطبعها صفحة الافتتاح أيضًا.

#4 · صفحة افتتاح واحدة، معكوسة للمحتويات

script.js · الأسطر 184–211في الشيفرة الكاملة
const corner = (id, edge) => ({ kind: 'image', id, resourceId: id,
  placement: { anchor: { to: 'bleed', edge }, size: { width: mm(CORNER.width) } } });
const months = { kind: 'text', id: 'months', content: '{attr.months}', ...label,
  color: col('accent'), placement: at('top-left', 0, 14, 'container') };
const title = { kind: 'text', id: 'title', content: '{titleText}', ...display, fontSize: pt(42),
  lineHeight: 1.05, align: 'left', overflow: 'wrap', placement: below('months', 1.5, 100) };
const opener = { enabled: true, minHeight: mm(52), slot: { elements: [
  corner('cells', 'top-right'),
  // The number's box is centred on its cell. Comb and number both hang from the bleed's top
  // right, so a bleed (page.cutLines) moves them together.
  { kind: 'text', id: 'number', content: '{chapterNumber}', ...display, fontSize: pt(40),
    lineHeight: 1, align: 'center', placement: { size: { width: mm(NUMBER.box) },
      ...at('top-right', NUMBER_CELL.x + NUMBER.box / 2 - CORNER.width,
        NUMBER_CELL.y - NUMBER.rise, 'bleed') } },
  months, title,
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: 'Andada Pro', italic: true,
    fontSize: pt(11.5), lineHeight: 1.35, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: below('title', 3, 88) },
] } };
// The contents mirror it on the verso: the comb in the outer corner, the book's subtitle and
// the title set flush right against the spine, on the same lines as Autumn's across the spread.
const flushRight = (element, placement) => ({ ...element, align: 'right',
  placement: { ...placement, size: { width: 'fill' } } });
const contentsOpener = { ...opener, minHeight: mm(40), slot: { elements: [
  corner('comb', 'top-left'),
  flushRight({ ...months, content: '{subtitle}' }, months.placement),
  flushRight(title, below('months', 1.5)),
] } };

يواصل {chapterNumber} العدّ مما أُخرج من المستندات قبله، فتطبع صفحة افتتاح Spring الرقم 3 مع أن ملفه لا يتضمّن أي رقم. يُحسب إطار الرقم من مركز خليته في القرص، ويتدلّى الرقم والقرص كلاهما من الركن الأيمن العلوي لمنطقة النزف، فإذا غيّرت حدّ القص أو أضفت نزفًا للطباعة تحرّكا معًا. وفي صفحة المحتويات يُنضَّد العنوان التمهيدي (kicker)، المقروء من {subtitle}، والعنوان ملاصقين للكعب إلى اليمين، وينتقل القرص إلى الركن الخارجي للصفحة الزوجية. فيقع عنوانها على ارتفاع عنوان Autumn نفسه في الصفحة المقابلة.

#5 · ترويسات في كل مستند

script.js · الأسطر 232–248في الشيفرة الكاملة
const head = (id, content, parity, placement, extra = {}) => ({
  kind: 'text', id, content, parity, pages: 'body', // never on openers or blank pages
  ...label, color: col('muted'), placement, ...extra,
});
const folio = { fontSize: pt(8.5), fontWeight: 700, color: col('accent') };
// Only the first document has frontmatter, and its {title} is the book's in every chapter.
const header = { elements: [
  head('verso-folio', '{pageNumber}', 'even', at('top-left', MARGIN.outer, HEAD.y), folio),
  head('verso-title', '{title}', 'even', at('top-left', MARGIN.outer + HEAD.gap, HEAD.y)),
  // {chapterTitle} and {pageNumber} are worked out page by page, in every document.
  head('recto-title', '{chapterTitle}', 'odd',
    at('top-right', -(MARGIN.outer + HEAD.gap), HEAD.y)),
  head('recto-folio', '{pageNumber}', 'odd', at('top-right', -MARGIN.outer, HEAD.y), folio),
] };
// Openers carry a drop folio instead, 8 mm under the text block.
const footer = { elements: [head('drop-folio', '{pageNumber}', 'all',
  at('top', 0, 8, 'container'), { pages: 'opener', fontWeight: 700 })] };

المستند الأول وحده فيه بيانات تمهيدية، وbuildBundle تسلّمها إلى كل فصل، فتطبع ترويسة الصفحة الزوجية {title} الكتاب في المستندات الخمسة. أما {chapterTitle} و{pageNumber} فيُحسبان لكل صفحة على حدة ويُطبعان في كل مستند؛ والصفحة 11، الصفحة اليمنى الوحيدة في المتن، عليها SUMMER بجوار رقمها. ويُبعد pages: 'body' كل ترويسة عن صفحات الافتتاح وعن الصفحة البيضاء.

#6 · صفحات متقابلة على الشاشة وملف PDF واحد للكتاب

script.js · الأسطر 369–379في الشيفرة الكاملة
const text = chapters.map((chapter) => chapter.markdown).join('\n');
await prepareFonts(text, config(), kitFonts(FONTS));
const art = { cover: coverArt(), cells: cornerArt(true), comb: cornerArt(false) };
for (const [season, plan] of Object.entries(SEASONS)) art[`${season}-frame`] = frameArt(plan);
for (const [id, markup] of Object.entries(art)) await loadSvg(`${id}.svg`, markup);
// One VDTDocument per Markdown document.
const docs = await withLoadedFonts(book, { ...kitFonts(FONTS), text });
showPages(docs, { title: t({ en: 'A Beekeeper’s Year', es: 'Un año de colmenar' }) });
// renderToPdf takes the array: one file for the book, with a bookmark per chapter.
offerPdf(() => renderToPdf(docs, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

يعيد buildBundle مصفوفة من المستندات، مستند لكل ملف Markdown. ويزاوج showPages بين الصفحات بحسب pageIndexOffset + page.index، فتقف الصفحة 1 وحدها صفحةً فردية، وتتقابل الصفحتان 2 و3، ثم 4 و5، وهكذا. ويأخذ renderToPdf المصفوفة نفسها ويكتب ملفًا واحدًا بأرقام صفحات الكتاب وإشارة مرجعية لكل فصل وقسم.

الوصفة كاملة

Sandbox
// ═══ Postext Cookbook · Nº 007 · One book from separate chapters ══════════════════════════
// https://postext.dev/en/cookbook/book-from-chapters
// Code: MIT · Text: original (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Andada Pro, Rozha One, Figtree (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A handbook in four seasons written as five Markdown documents, laid out by buildBundle as
// one book: parity, folios, chapter and figure numbers and the contents run straight through.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
} 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 = 'book-from-chapters';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // every colour in the config links to one of these, so the book can be retinted
  ink: '#2a2218', // text and display type
  honey: '#d99a1e', // the drawings only: the cover and the comb cells
  accent: '#7a4e12', // the text accent (7:1 on paper): numbers, labels, subheads; main-color too
  pollen: '#c4692b', comb: '#f7e7c4', rule: '#d8c8a8', // figures: pollen, wax, wood and walls
  muted: '#6e634f', paper: '#fffdf7', // running heads, colophon, contents sections; the page
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// The geometry, in mm. The drawings, the opener and the running heads are derived from it.
const TRIM = { width: 150, height: 200 }; // a small handbook
const MARGIN = { top: 22, bottom: 22, inner: 19, outer: 15 }; // mirrored
const MEASURE = TRIM.width - MARGIN.inner - MARGIN.outer; // the text width: 116 mm
const SQRT3 = Math.sqrt(3); // comb cells of radius r sit √3·r apart, their rows 1.5·r apart
const CORNER = { width: 84, height: 70, r: 9.5 }; // the openers' comb, and its cell radius
const NUMBER_CELL = { x: 4 * SQRT3 * CORNER.r, y: 2 * 1.5 * CORNER.r }; // row 2, cell 4
// The chapter number's box: 20 mm wide, its top 8 mm above the cell's centre, which is where
// a 40 pt Rozha One figure sits optically centred in the cell.
const NUMBER = { box: 20, rise: 8 };
const FRAME = { width: MEASURE, height: 50 }; // the brood frame figures, at the text width
const HEAD = { y: 12, gap: 8 }; // running heads 12 mm from the top edge, 8 mm folio to text
const LEAD = 14.2; // body leading in pt: the baseline grid
// The look: a small handbook, mirrored, justified Andada Pro on the grid; Rozha One titles.
const page = { // mirror: left is the inner margin, right the outer
  sizePreset: 'custom', width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
  backgroundColor: col('paper'), margins: { top: mm(MARGIN.top), bottom: mm(MARGIN.bottom),
    left: mm(MARGIN.inner), right: mm(MARGIN.outer), mirror: true },
};
const bodyText = { // justified, hyphenated, optimal line breaks and widow control: by default

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

تنويعات

#اطبع فصلًا واحدًا بأرقام صفحاته في الكتاب

مرّر مستندًا واحدًا إلى renderToPdf لتراجع بروفة Spring وحده، مرقّمًا من 6 إلى 8 كما في الكتاب. وتأتي معه الصفحة البيضاء 6، لأن الصفحة الزوجية البيضاء التي تسبق صفحة افتتاح تنتمي إلى الفصل الذي يبدأ بعدها.

-offerPdf(() => renderToPdf(docs, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
+offerPdf(() => renderToPdf(docs[3], { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),

#رقّم الأشكال ترقيمًا متصلًا في الكتاب كله

عدّاد أشكال لا يُصفَّر أبدًا يرقّم الإطارات الأربعة من 1 إلى 4 عبر المستندات بدلًا من 1.1 إلى 4.1.

   buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
+  defaultResourceTypes,
@@
   locale: t({ en: 'en-us', es: 'es' }),
+  resourceTypes: defaultResourceTypes(LANG)
+    .map((type) => ({ ...type, numberingTemplate: '{n}', resetOn: 'never' })),

أخطاء شائعة

خطأ شائع

يرث نمط العنوان فاصل الصفحة من مستواه

يأخذ مُدخل headingStyles كل حقل يتركه من مستوى عنوانه، بما فيه breakBefore. فصفحة المحتويات أو صفحة بيانات النشر المنسّقة على H1 بعد :::pagebreak ترث الزوجية 'odd' وتقع بعد صفحة فارغة. أعطِ هذا النمط breakBefore: { enabled: false }. أنماط العناوين →

خطأ شائع

الصفحة 1 فردية: خطّط الصفحات بأرقامها الفعلية

الصفحة 1 صفحة يمنى والصفحة 2 أول صفحة زوجية، فخطّط الصفحتين المتقابلتين بأرقام الصفحات الفعلية: الافتتاحية في صفحة زوجية تقابل الصفحة الفردية التي تليها. فواصل الصفحات والأعمدة →

فحص Sandbox · chapterFrontmatterIgnored

تجاهل البيانات التمهيدية للفصل

السبب. لا تُحتسب إلا البيانات التمهيدية (frontmatter) للفصل الأول؛ وإذا بدأ فصل لاحق بكتلة بيانات تمهيدية أُسقطت.

الحل. احتفظ بالبيانات الوصفية للكتاب في الفصل الأول، واستعمل سمات العناوين للقيم الخاصة بكل فصل. التوثيق →

  • في رأس الصفحة، وتحت شكل يتصدّر الصفحة، يفقد العنوان الفرعي قيمة marginTop. فالعنوان الفرعي الذي يأخذ مسافته من الهامش يقف فوق نصه بسطر واحد في هذين الموضعين، وبسطر ونصف في كل موضع آخر. وهنا المسافة جزء من سطر العنوان الفرعي نفسه: lineHeight سطر ونصف والهامش سطر واحد، فيقف كل عنوان فرعي في الكتاب على المسافة نفسها فوق نصه.
  • السطر المضبوط يستطيع افتراضيًا أن يمدّ مسافاته إلى ضعف عرضها، ويفضّل مقسّم الأسطر ذلك على الواصلة. وبهذه القيمة الافتراضية خلت الطبعة الإنجليزية من الواصلات تمامًا، وجاورت أسطرٌ تقترب مسافاتها من ضعف العرض العادي أسطرًا مضغوطة إلى 0.7. يجعل maxWordSpacing: 1.7 المقسّمَ يلجأ إلى الواصلة بدلًا من ذلك. وبعد تغييره، افحص السطر الأخير من كل فقرة: قد يترك الحدّ الأضيق كلمة واحدة هناك، وتعيد صياغة بضع كلمات من الفقرة تصلح ذلك.

الحقوق

الوصفة
Ignacio Ferro
النص
نص أصلي, CC BY 4.0
الخطوط
Andada Pro (SIL OFL 1.1) · Rozha One (SIL OFL 1.1) · Figtree (SIL OFL 1.1)
الشيفرة
MIT، مثل Postext
SandboxPDF