Saltar al contingut principal
Recepta número 9

Receptari · Capítol 7 · Figures i imatges

Figures que suren fins on les cites

Capítol a dues columnes amb set figures numerades: sis suren del primer :ref al primer buit que admet la seva col·locació; una va on la posa ::resource.

En aquesta pàgina
Sortida
Canvas
Nivell
Avançat
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.25.0
Llicència
Actualitzada el 11 d’oct. del 2026
Codi MIT · Text CC BY 4.0

pp. 28–29 · 2–3 de 4

  • Mostra en castellà: encara no hi ha edició en català
  • Format 200 × 250 mm
  • 2 columnes, espai entre columnes de 6 mm
  • Faustina 9,4/13,4
  • IBM Plex Sans Condensed
  • Montserrat
  • 4 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 172 ms
  • 224 línies de codi

En poques paraules

Un capítol d'un llibre de text sobre muntanyes, a dues columnes, amb set figures numerades. Ensenya com cada figura es col·loca al primer espai lliure després que el text l'esmenti.

Què compondràs

El capítol 2 de Relleus de muntanya, un manual de geomorfologia de 200 × 250 mm. A l'obertura, una cinta blava amb un 2 blanc penja al costat de la llosa blau gel del títol; segueixen dues columnes de Faustina justificada. Les set figures, pintures generades amb models de difusió i retolades en codi, es numeren segons la primera menció. Sis suren fins al primer buit que admet la seva col·locació, comptant des del paràgraf que les cita per primera vegada. La 2.1, auto, cau al peu de l'obertura; la 2.3 obre la columna dreta de la pàgina 28 i la 2.2 ocupa el peu d'aquesta pàgina; la 2.4 i la 2.5 obren les dues columnes de la 29. La 2.6 va on el text la insereix. La 2.7 és top i se cita a la pàgina 30; esperaria a la 31, però no pot sortir del capítol i queda al peu de la 30.

Aquesta recepta respon a

  • Com afegeixo una figura amb peu numerat i la cito en el text («vegeu la fig. 3.2»)?
  • Com decideixo on va una figura: al capdamunt de la pàgina, a l'amplada de les dues columnes, just aquí o al marge?
  • Com aconsegueixo les etiquetes «Figura» i «Taula» en la llengua del meu document?
  • Com afegeixo imatges i taules des del codi (recursos) en lloc de ![]() de Markdown?

La resposta curta

script.js · línies 252–285al codi complet
// In the Markdown, :ref{id="valleys" case="lower"} prints 'fig. 2.1' and places Figure 2.1.
// Captions, credits and alt texts come from content.figures.<lang>.md.
const figure = (id, height, placement) => {
  if (!TEXTS[id]) throw new Error(`content.figures has no caption block for "${id}"`);
  const [caption, note, altText] = TEXTS[id];
  // An SVG fills the width of its slot (a column or the text block, or a fraction of
  // either), so its width and height only give its shape.
  const width = (placement.span === 'page' ? MEASURE : COLUMN) * (placement.width ?? 1);
  return { id, typeId: 'figure', kind: 'svg', caption, note, altText,
    svg: { fileId: `${id}.svg`, width, height }, placement, createdAt: 0, updatedAt: 0 };
};
// In any order: the first mention of each one in the text, a :ref or a ::resource line,
// decides its number.
const resources = [
  // Cited on the opener page: 'auto' may take that page's foot band, where 'top'
  // could only open the next page (gotcha: top-float-next-page).
  figure('valleys', 56, { position: 'auto', span: 'page' }),
  // Across both columns, but only in a foot band: the page it is cited on, if both
  // columns still have room there, else the foot of the next page.
  figure('profile', 60, { position: 'bottom', span: 'page' }),
  // A column figure that takes only a column head: the next one still empty after its
  // citation, here the right column of the same page, above the text that follows it.
  figure('cirque', 48, { position: 'top' }),
  // Cited in the same sentence, the two take the next two column heads, side by side.
  figure('abrasion', 48, { position: 'top' }),
  figure('plucking', 48, { position: 'top' }),
  // No float: set exactly where ::resource{id="roche"} stands, with the same gap above it
  // and below it.
  figure('roche', 42, { position: 'here' }),
  // A band of its own, half the text width and centred. It is cited on the chapter's last
  // page, where a 'top' float would wait for the next page; a float cannot leave its
  // chapter, so this one goes to the foot of the last page.
  figure('moraines', 50, { position: 'top', span: 'page', width: 0.5, align: 'center' }),
];

Ingredients

També fa servir
Estils de paràgraf
Tipografia
Faustina, Montserrat, IBM Plex Sans Condensed (SIL OFL 1.1)
Recursos
  • abrasion-1080.jpg
  • cirque-1080.jpg
  • moraines-1080.jpg
  • plucking-1080.jpg
  • profile-1400.jpg
  • roche-1080.jpg
  • valleys-1536.jpg
  • Figure 2.1: a V-shaped river valley and a U-shaped glacial valley (Generated With Diffusion Models, original)
  • Figure 2.2: long profile of a valley glacier (Generated With Diffusion Models, original)
  • Figure 2.3: a glacial cirque in section (Generated With Diffusion Models, original)
  • Figure 2.4: abrasion at the base of the ice (Generated With Diffusion Models, original)
  • Figure 2.5: plucking on a rock step (Generated With Diffusion Models, original)
  • Figure 2.6: a roche moutonnée (Generated With Diffusion Models, original)
  • Figure 2.7: lateral, medial and terminal moraines in plan (Generated With Diffusion Models, original)

Elaboració

#1 · Una sola paleta per a pàgines i figures

script.js · línies 19–36al codi complet
const palette = {
  ink: '#1b2227', // text: a cold near-black
  glacier: '#34729a', // the accent: kicker, ribbon, caption labels, references, folios, water
  ice: '#e3f1f8', // the opener slab
  rock: '#5b5a57', // bedrock in the drawings
  moss: '#7d8f4e', // valley floors and pines
  rule: '#c6d3db', // the hairline under the running heads
  muted: '#5d6a72', // running heads, credit notes, the colophon
  paper: '#ffffff',
};
// A linked 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).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color' (#295aa3): pointing it at the accent keeps
  // that second blue off the page.
  { id: 'main-color', name: 'glacier (defaults)', value: { hex: palette.glacier, model: 'hex' } },
];

Cada color de la configuració enllaça amb una d'aquestes entrades, i les pintures es van generar en els mateixos pissarra, blau glacera i molsa, de manera que les figures entren en els colors de la pàgina. Una pintura conserva els seus colors: si canvies el valor de glacier, canvien la cinta, la llosa i els rètols, no el gel de les figures. El blau d'accent és prou fosc per a la lletra petita: contrasta 5,2:1 amb el blanc a les etiquetes dels peus i a les cites, i 4,5:1 amb la llosa de gel a l'avantítol. Cada figura és un SVG que incrusta la seva pintura com un JPEG en data URL i hi posa al damunt els rètols com a text, amb un halo blanc fi, perquè es llegeixin nítids i segueixin la llengua de l'edició. Indiquen IBM Plex Sans Condensed al mateix SVG, i el loadSvg del kit hi incrusta els dos gruixos que fan servir amb l'inlineSvgFonts del motor, perquè un SVG mostrat com a imatge no arriba tot sol a les fonts de la pàgina.

#2 · Anomena les figures en la llengua del lector

script.js · línies 47–56al codi complet
const captions = () => ({
  // The built-in types take their names from the locale: 'Figure 2.3' and 'fig. 2.3' with
  // 'en-us', 'Figura 2.3' with 'es', numbered {h1}.{n} per chapter. It sets hyphenation too.
  locale: t({ en: 'en-us', es: 'es' }),
  captionStyle: { // the text colour follows bodyText; the note is 0.85 × the caption size
    fontFamily: LABEL, fontSize: pt(8.3), gap: mm(2.2),
    labelColor: col('glacier'), descriptionItalic: true, // the label is bold by default
    note: { color: col('muted'), gap: mm(0.6) }, // the credit line
  },
});

locale dona als tipus integrats els noms en la llengua del document, i així els peus diuen Figura 2.3 en aquesta edició i Figure 2.3 en l'anglesa. El mateix 'es' tria els patrons de partició de mots de l'espanyol. Cada cita pren després la forma que demana la seva frase: case="lower" per al parèntesi (fig. 2.1) i, amb style="full", per a (figura 2.2); style="number" després d'un plural (les figures 2.4 i 2.5); i text="…" per a una perífrasi com la primera figura del capítol, que no imprimeix número. Aquí remet a una figura ja col·locada; com a primera menció, també la numeraria i la col·locaria.

#3 · Una cinta i una llosa de gel per a l'obertura

script.js · línies 60–110al codi complet
const at = (to, edge, x, y, width, height) => ({ anchor: { to, edge },
  offset: { x: mm(x), y: mm(y) },
  ...(width && { size: { width: mm(width), height: height ? mm(height) : 'auto' } }) });
const text = (id, content, family, size, color, placement, extra) => ({ kind: 'text', id,
  content, fontFamily: family, fontSize: pt(size), color: col(color), placement,
  align: 'left', ...extra });
const caps = (size) => ({ fontWeight: 600, textTransform: 'uppercase',
  letterSpacing: pt(size * 0.18) }); // capitals tracked 0.18 em
const [SLAB, RIBBON, RIBBON_END] = [64, 30, 70]; // mm: slab height; ribbon width and length
const [TEXT_X, KICKER_Y] = [RIBBON + 8, 10]; // mm: the opener texts start 8 mm right of the ribbon
const [TITLE_W, LEAD_W] = [118, 112]; // mm: the title's measure, and a shorter standfirst
const opener = {
  enabled: true,
  // At least 5 mm under the slab; the reserve then rounds up to whole 13.4 pt grid lines,
  // so here 69 mm becomes 15 lines (70.9 mm) and the text starts about 7 mm under the slab.
  minHeight: mm(SLAB + 5),
  slot: { elements: [
    { kind: 'box', id: 'slab', style: { backgroundColor: col('ice') }, // runs off the fore-edge
      placement: at('container', 'top-left', 0, 0, MEASURE + OUTER, SLAB) },
    { kind: 'box', id: 'ribbon', style: { backgroundColor: col('glacier') }, // hangs from the head
      placement: at('page', 'top-left', INNER, 0, RIBBON, RIBBON_END) },
    text('numeral', '{chapterNumber}', DISPLAY, 80, 'paper', // an 80 pt line box is 28 mm tall:
      at('page', 'top-left', INNER, RIBBON_END - 31, RIBBON), // it ends 3 mm above the foot
      { fontWeight: 800, lineHeight: 1, align: 'center' }),
    text('kicker', t({ en: 'Chapter {chapterNumber} · {attr.topic}',
      es: 'Capítulo {chapterNumber} · {attr.topic}' }), LABEL, 8.5, 'glacier',
    at('container', 'top-left', TEXT_X, KICKER_Y), caps(8.5)),
    text('title', '{titleText}', DISPLAY, 27, 'ink', at('#kicker', 'below', 0, 2.6, TITLE_W),
      { fontWeight: 800, lineHeight: 1.06 }),
    text('lead', '{attr.lead}', TEXT, 10.6, 'ink', at('#title', 'below', 0, 4.2, LEAD_W),
      { italic: true, lineHeight: 1.38, hyphenate: true }),
  ] },
};
const HAIRLINE = TOP - 5; // mm from the top edge: the rule under the running heads
const HEAD_Y = HAIRLINE - 4.4; // the running heads' line box, 4.4 mm above the hairline
const head = (id, content, parity, edge, x, extra) => text(id, content, LABEL, 7.6, 'muted',
  at('page', edge, x, HEAD_Y), { ...caps(7.6), parity, pages: 'body', ...extra });
const folio = (id, parity, edge, x, extra) => text(id, '{pageNumber}', DISPLAY, 8.5, 'glacier',
  at('page', edge, x, HEAD_Y), { fontWeight: 800, parity, pages: 'body', ...extra });
const header = { elements: [ // outer corners, over a hairline; never on the opener
  folio('verso-folio', 'even', 'top-left', OUTER),
  head('verso-title', '{title}', 'even', 'top-left', OUTER + 8),
  head('recto-title', '{chapterTitle}', 'odd', 'top-right', -(OUTER + 8), { align: 'right' }),
  folio('recto-folio', 'odd', 'top-right', -OUTER, { align: 'right' }),
  { kind: 'rule', id: 'hairline', pages: 'body', direction: 'horizontal', color: col('rule'),
    thickness: pt(0.5), placement: { ...at('container', 'top-left', 0, HAIRLINE),
      size: { width: 'fill', height: 'auto' } } },
] };
const footer = { elements: [ // the drop folio: on the opener only, centred 9 mm under the text
  text('drop-folio', '{pageNumber}', DISPLAY, 8.5, 'glacier', at('container', 'top', 0, 9),
    { fontWeight: 800, align: 'center', pages: 'opener' })] };

L'obertura es compon de dues caixes i quatre textos: una cinta que penja del capçal amb el número del capítol al peu, una llosa de gel que surt a sang pel tall exterior, l'avantítol pres de l'atribut topic del títol, i el títol i l'entradeta encadenats a sota. minHeight reserva la llosa i com a mínim 5 mm a sota, arrodonits cap amunt a línies senceres de la retícula de base (uns 7 mm aquí), de manera que la figura 2.1 encara cap a la banda del peu de la mateixa pàgina. Les capçaleres van a les cantonades exteriors sobre un filet del color rule, i pages: 'body' les treu de l'obertura, que porta en el seu lloc un foli al peu.

#4 · Atura't davant d'un identificador desconegut o d'una figura sense citar

script.js · línies 289–310al codi complet
// The build lists every :ref and ::resource to an id no resource has in doc.contentWarnings
// (kind 'unknownResourceId'); each prints '?' on the page. A figure nobody names is never
// placed and raises no warning, so the pen reads the mentions with the engine's own parser;
// an embed needs double quotes (gotcha: resource-double-quotes).
function checkFigures(doc) {
  const [named, embedded] = [new Set(), new Set()];
  for (const block of parseMarkdown(markdown)) {
    if (block.type === 'resourceBlock' && block.resourceId) {
      named.add(block.resourceId);
      embedded.add(block.resourceId);
    }
    for (const span of block.spans) if (span.ref?.resourceId) named.add(span.ref.resourceId);
  }
  const unknown = (doc.contentWarnings ?? []).filter((w) => w.kind === 'unknownResourceId');
  const problems = [
    ...new Set(unknown.map((w) => `unknown id "${w.resourceId}"`)),
    ...resources.filter((r) => !named.has(r.id)).map((r) => `"${r.id}" is never cited`),
    ...resources.filter((r) => r.placement.position === 'here' && !embedded.has(r.id))
      .map((r) => `"${r.id}" is placed 'here' but no ::resource line embeds it`),
  ];
  if (problems.length) throw new Error(`Figures: ${problems.join('; ')}`);
}

Un :ref o un ::resource a un id que cap recurs no té imprimeix «?» i no col·loca res; la composició anota cadascun a doc.contentWarnings com a unknownResourceId, amb l'id i el seu lloc al text font. Una figura que ningú no esmenta no es col·loca mai i no produeix cap avís, de manera que la comprovació llegeix el Markdown amb parseMarkdown, l'analitzador del mateix motor, i compara les mencions amb les figures. Un id desconegut, una figura sense citar o una figura here sense la seva línia ::resource es converteixen en un únic error abans de mostrar les pàgines.

#5 · Comença a comptar per on va el llibre

script.js · línies 417–429al codi complet
for (const { id, svg: { fileId, width, height } } of resources) { // each under its svg.fileId
  const art = await dataUrl(PAINTINGS[id]);
  await loadSvg(fileId, svg(width, height, `<image href="${art}" width="${n2(width)}" `
    + `height="${n2(height)}" preserveAspectRatio="none"/>${DRAWINGS[id](width, height)}`));
}
// One chapter came before: figures number 2.1, 2.2… and the folios start at 27.
const continuation = { pageNumbering: { startAt: 27 }, // odd, to match the recto of page 1
  headings: { h1: 1, h2: 0, h3: 0, h4: 0, h5: 0, h6: 0 } }; // the next # is chapter 2
const doc = await buildDocumentWithFonts({ markdown, resources, continuation }, config(),
  { ...kitFonts(FONTS), text: words });
checkFigures(doc); // a wrong id stops here, and the viewer's bar says why
showPages(doc, { title: t({ en: 'Figures that float to where you cite them',
  es: 'Figuras que flotan hasta donde las citas' }) });

Aquest és el capítol 2 d'un llibre més llarg, així que la continuació indica que abans hi va haver un capítol: les figures, numerades {h1}.{n}, comencen a la 2.1, i els folis, al 27. A la pàgina 28, la figura 2.3 queda per sobre de la 2.2, que porta el número menor perquè el text la cita abans. El ![]() de Markdown es descarta, així que cada figura és un recurs amb un SVG que es registra sota el seu svg.fileId abans de compondre. Cada col·locació depèn d'on se cita la figura: auto per a la 2.1, perquè la llosa ocupa el capçal de l'obertura; bottom per al perfil, que encara pot ocupar el peu de la pàgina que el cita; top per a les figures de columna, que obren els capçals de columna lliures següents, i també top per a la 2.7, que acaba al peu de la pàgina 30 perquè un flotant no surt del seu capítol.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 009 · Figures that float to where you cite them ═════════
// https://postext.dev/en/cookbook/figures-float-where-cited
// Code: MIT · Text: original (CC BY 4.0) · Figures: diffusion models, labels in code
// Fonts: Faustina, Montserrat, IBM Plex Sans Condensed (SIL OFL 1.1) · Needs postext ≥ 1.25.0
//
// Chapter 2 of a geomorphology textbook. Six of its seven figures float, each to the first
// free slot its placement allows, counting from the paragraph that first cites it. Figure 2.6
// is set where ::resource embeds it. The figures are numbered in order of first mention.
import {
  buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage,
  inlineSvgFonts, parseMarkdown,
} from 'https://esm.sh/postext';

const LANG = 'es'; // @lang: the language of the sample document ('es' | 'en')
const RECIPE = 'figures-float-where-cited';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: eight named colours; the paintings were made to match them
const palette = {
  ink: '#1b2227', // text: a cold near-black
  glacier: '#34729a', // the accent: kicker, ribbon, caption labels, references, folios, water
  ice: '#e3f1f8', // the opener slab
  rock: '#5b5a57', // bedrock in the drawings
  moss: '#7d8f4e', // valley floors and pines
  rule: '#c6d3db', // the hairline under the running heads
  muted: '#5d6a72', // running heads, credit notes, the colophon
  paper: '#ffffff',
};
// A linked 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).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color' (#295aa3): pointing it at the accent keeps
  // that second blue off the page.
  { id: 'main-color', name: 'glacier (defaults)', value: { hex: palette.glacier, model: 'hex' } },
];
// #endregion
const TEXT = 'Faustina'; // one family each for text, display and labels
const DISPLAY = 'Montserrat';
const LABEL = 'IBM Plex Sans Condensed';
const LEAD = 13.4; // body leading in pt: the grid every float band snaps to
const [PAGE_W, PAGE_H, TOP, BOTTOM, INNER, OUTER, GUTTER] = [200, 250, 22, 20, 18, 14, 6]; // mm
const MEASURE = PAGE_W - INNER - OUTER; // 168 mm: the text block, and a page-wide figure
const COLUMN = (MEASURE - GUTTER) / 2; // 81 mm: a column, and a column figure

// #region captions: the type name in the document's language; bold label, italic description
const captions = () => ({
  // The built-in types take their names from the locale: 'Figure 2.3' and 'fig. 2.3' with

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Numera les figures sense el capítol

Treu el capítol dels números i les figures aniran de la 1 a la 7; per a una numeració seguida en tot el llibre, compon els capítols amb buildBundle o passa a cada capítol el continuationAfter() de l'anterior.

-  inlineSvgFonts, parseMarkdown,
+  inlineSvgFonts, parseMarkdown, defaultResourceTypes,
@@
   locale: t({ en: 'en-us', es: 'es' }),
+  resourceTypes: defaultResourceTypes(LANG).map((type) => ({ ...type,
+    numberingTemplate: '{n}', resetOn: 'never' })),

#Posa els peus a dalt, sobre una barra

El peu puja per sobre de la figura, sobre una barra del blau gel de la paleta, i la línia de crèdit es queda sota la figura; reajusta el text, perquè llavors les dues edicions ocupen cinc pàgines.

   captionStyle: { // the text colour follows bodyText; the note is 0.85 × the caption size
+    position: 'above', backgroundEnabled: true, background: col('ice'),
     fontFamily: LABEL, fontSize: pt(8.3), gap: mm(2.2),

#Posa una figura al marge

Una pàgina a columna i mitja dona a les figures i als seus peus una columna lateral exterior on el text no entra mai: mira el llibre de text amb columna al marge.

#Fes surar les taules igual

Les taules també són recursos, se citen i es col·loquen amb les mateixes regles, i una taula llarga es reparteix entre diverses pàgines: mira el full tècnic.

Errors freqüents

Error freqüent

Un flotant 'top' va a la pàgina següent a la seva cita tret que pugui encapçalar la pàgina que el cita

Per defecte un flotant no va mai per sobre de la seva pròpia referència, així que un flotant 'top' a tota l'amplada citat a la pàgina N obre la pàgina N+1. Amb placement.citingPage: true al recurs o al defaultPlacement del seu tipus (o layout.floatsAtCitingPage per a tot el llibre, des de postext 1.25) encapçala en canvi la pàgina N, i el text de damunt de la referència baixa sota seu, quan hi cap dins de layout.maxTopFraction i la línia que el cita continua en aquesta pàgina. No encapçala mai la primera pàgina d'un capítol ni una pàgina després d'un salt forçat: allà continua obrint la pàgina següent, i 'auto' o 'bottom' poden ocupar el peu de la pàgina que el cita. Col·locació de figures →

Error freqüent

::resource{id="…"} només admet cometes dobles

Una inserció de bloc només es reconeix com a ::resource{id="…"} amb cometes dobles; qualsevol altra forma es queda al text com una línia visible. Figures just aquí →

Error freqüent

Sense <marker> ni filtres als SVG, o passen a mapa de bits

Una figura SVG només continua sent vectorial al PDF sense <marker>, filtres ni màscares; si no, passa a mapa de bits, i els filtres molt imbricats la poden deixar en blanc a Chrome. Dibuixa les puntes de fletxa com a traçats. Figures i taules com a recursos →

Comprovació del Sandbox · unknownResourceId

Recurs desconegut

Per què. Un :ref o un ::resource fa servir un id que no té cap recurs; la referència imprimeix «?» i no es col·loca res.

Solució. Corregeix l'id (només amb cometes dobles) o afegeix el recurs. Documentació →

Crèdits

Text
Text original, CC BY 4.0
Imatges
  • Figure 2.1: a V-shaped river valley and a U-shaped glacial valley · Generated With Diffusion Models · original
  • Figure 2.2: long profile of a valley glacier · Generated With Diffusion Models · original
  • Figure 2.3: a glacial cirque in section · Generated With Diffusion Models · original
  • Figure 2.4: abrasion at the base of the ice · Generated With Diffusion Models · original
  • Figure 2.5: plucking on a rock step · Generated With Diffusion Models · original
  • Figure 2.6: a roche moutonnée · Generated With Diffusion Models · original
  • Figure 2.7: lateral, medial and terminal moraines in plan · Generated With Diffusion Models · original
Fonts
Faustina (SIL OFL 1.1) · Montserrat (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1)
Sandbox