Saltar al contenido principal
Receta número 9

Recetario · Capítulo 7 · Figuras e imágenes

Figuras que flotan hasta donde las citas

Capítulo a dos columnas con siete figuras numeradas: seis flotan de su primer :ref al primer hueco que admite su colocación; una va donde la pone ::resource.

En esta página
Salida
Canvas
Postext
Probada con Postext 1.65.0
Requiere ≥ 1.25.0
Licencia
Actualizada el 11 oct 2026
Código MIT · Texto CC BY 4.0

pp. 28–29 · 2–3 de 4

  • Formato 200 × 250 mm
  • 2 columnas, medianil de 6 mm
  • Faustina 9,4/13,4
  • IBM Plex Sans Condensed
  • Montserrat
  • 4 páginas
  • Nivel
  • Postext 1.65.0
  • Compuesto en 172 ms
  • 224 líneas de código

En pocas palabras

Un capítulo de un libro de texto sobre montañas, a dos columnas, con siete figuras numeradas. Enseña cómo cada figura se coloca en el primer hueco libre después de que el texto la mencione.

Lo que vas a componer

El capítulo 2 de Relieves de montaña, un manual de geomorfología de 200 × 250 mm. En la apertura, una cinta azul con un 2 blanco cuelga junto a la losa azul hielo del título; siguen dos columnas de Faustina justificada. Las siete figuras, pinturas generadas con modelos de difusión y rotuladas en código, se numeran según su primera mención. Seis flotan hasta el primer hueco que admite su colocación, contando desde el párrafo que las cita por primera vez. La 2.1, auto, cae al pie de la apertura; la 2.3 abre la columna derecha de la página 28 y la 2.2 ocupa el pie de esa página; la 2.4 y la 2.5 abren las dos columnas de la 29. La 2.6 va donde el texto la inserta. La 2.7 es top y se cita en la página 30; esperaría a la 31, pero no puede salir del capítulo y queda al pie de la 30.

Esta receta responde a

  • ¿Cómo añado una figura con pie numerado y la cito en el texto («véase la fig. 3.2»)?
  • ¿Cómo decido dónde va una figura: en la cabeza de la página, a lo ancho de las dos columnas, justo aquí o al margen?
  • ¿Cómo consigo las etiquetas «Figura» y «Tabla» en el idioma de mi documento?
  • ¿Cómo añado imágenes y tablas desde el código (recursos) en lugar de ![]() de Markdown?

La respuesta corta

script.js · líneas 252–285en el código completo
// 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' }),
];

Ingredientes

Tipografía
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
  • Figura 2.1: un valle fluvial en V y un valle glaciar en U (Generated With Diffusion Models, original)
  • Figura 2.2: perfil longitudinal de un glaciar de valle (Generated With Diffusion Models, original)
  • Figura 2.3: un circo glaciar en sección (Generated With Diffusion Models, original)
  • Figura 2.4: abrasión en la base del hielo (Generated With Diffusion Models, original)
  • Figura 2.5: arranque en un resalte rocoso (Generated With Diffusion Models, original)
  • Figura 2.6: una roca aborregada (Generated With Diffusion Models, original)
  • Figura 2.7: morrenas laterales, central y frontal en planta (Generated With Diffusion Models, original)

Elaboración

#1 · Una sola paleta para páginas y figuras

script.js · líneas 19–36en el código completo
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ón enlaza con una de estas entradas, y las pinturas se generaron en los mismos pizarra, azul glaciar y musgo, así que las figuras entran en los colores de la página. Una pintura conserva sus colores: si cambias el valor de glacier, cambian la cinta, la losa y los rótulos, no el hielo de las figuras. El azul de acento es lo bastante oscuro para la letra pequeña: contrasta 5,2:1 con el blanco en las etiquetas de los pies y en las citas, y 4,5:1 con la losa de hielo en el antetítulo. Cada figura es un SVG que incrusta su pintura como un JPEG en data URL y pone encima los rótulos como texto, con un halo blanco fino, para que se lean nítidos y sigan el idioma de la edición. Indican IBM Plex Sans Condensed en el propio SVG, y el loadSvg del kit incrusta los dos pesos que usan con el inlineSvgFonts del motor, porque un SVG mostrado como imagen no alcanza por sí solo las fuentes de la página.

#2 · Nombra las figuras en el idioma del lector

script.js · líneas 47–56en el código completo
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 da a los tipos integrados sus nombres en el idioma del documento, y así los pies dicen Figura 2.3 en esta edición y Figure 2.3 en la inglesa. El mismo 'es' elige los patrones de separación silábica del español. Cada cita toma luego la forma que pide su frase: case="lower" para el paréntesis (fig. 2.1) y, con style="full", para (figura 2.2); style="number" tras un plural (las figuras 2.4 y 2.5); y text="…" para una perífrasis como la primera figura del capítulo, que no imprime número. Aquí remite a una figura ya colocada; como primera mención, también la numeraría y la colocaría.

#3 · Una cinta y una losa de hielo para la apertura

script.js · líneas 60–110en el código completo
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' })] };

La apertura se compone de dos cajas y cuatro textos: una cinta que cuelga de la cabeza con el número del capítulo al pie, una losa de hielo que sale a sangre por el corte exterior, el antetítulo tomado del atributo topic del título, y el título y la entradilla encadenados debajo. minHeight reserva la losa y al menos 5 mm bajo ella, redondeados hacia arriba a líneas enteras de la rejilla base (unos 7 mm aquí), de modo que la figura 2.1 aún cabe en la banda del pie de la misma página. Las cabeceras van en las esquinas exteriores sobre un filete del color rule, y pages: 'body' las saca de la apertura, que lleva en su lugar un folio al pie.

#4 · Detente ante un identificador desconocido o una figura sin citar

script.js · líneas 289–310en el código completo
// 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 ningún recurso tiene imprime «?» y no coloca nada; la composición anota cada uno en doc.contentWarnings como unknownResourceId, con el id y su lugar en el texto fuente. Una figura que nadie menciona no se coloca nunca y no produce ningún aviso, así que la comprobación lee el Markdown con parseMarkdown, el analizador del propio motor, y compara las menciones con las figuras. Un id desconocido, una figura sin citar o una figura here sin su línea ::resource se convierten en un único error antes de mostrar las páginas.

#5 · Empieza a contar por donde va el libro

script.js · líneas 417–429en el código completo
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' }) });

Este es el capítulo 2 de un libro más largo, así que la continuación indica que antes hubo un capítulo: las figuras, numeradas {h1}.{n}, empiezan en la 2.1, y los folios, en el 27. En la página 28, la figura 2.3 queda por encima de la 2.2, que lleva el número menor porque el texto la cita antes. El ![]() de Markdown se descarta, así que cada figura es un recurso cuyo SVG se registra bajo su svg.fileId antes de componer. Cada colocación depende de dónde se cita la figura: auto para la 2.1, porque la losa ocupa la cabeza de la apertura; bottom para el perfil, que aún puede ocupar el pie de la página que lo cita; top para las figuras de columna, que abren las siguientes cabezas de columna libres, y también top para la 2.7, que acaba al pie de la página 30 porque un flotante no sale de su capítulo.

La receta 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

El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)

Variantes

#Numera las figuras sin el capítulo

Quita el capítulo de los números y las figuras irán de la 1 a la 7; para una numeración corrida en todo el libro, compón los capítulos con buildBundle o pasa a cada capítulo el continuationAfter() del anterior.

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

#Pon los pies encima, sobre una barra

El pie sube por encima de la figura, sobre una barra del azul hielo de la paleta, y la línea de crédito se queda bajo la figura; reajusta el texto, porque entonces las dos ediciones ocupan cinco páginas.

   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),

#Pon una figura al margen

Una página a columna y media da a las figuras y a sus pies un canal exterior en el que nunca entra el texto: mira el libro de texto con columna al margen.

#Haz flotar las tablas igual

Las tablas también son recursos, se citan y se colocan con las mismas reglas, y una tabla larga se reparte entre varias páginas: mira la hoja técnica.

Errores frecuentes

Error frecuente

Un flotante 'top' va a la página siguiente a su cita salvo que pueda encabezar la página que lo cita

Por defecto un flotante nunca va por encima de su propia referencia, así que un flotante 'top' a todo el ancho citado en la página N abre la página N+1. Con placement.citingPage: true en el recurso o en el defaultPlacement de su tipo (o layout.floatsAtCitingPage para todo el libro, desde postext 1.25) encabeza en cambio la página N, y el texto de encima de la referencia baja bajo él, cuando cabe dentro de layout.maxTopFraction y la línea que lo cita sigue en esa página. Nunca encabeza la primera página de un capítulo ni una página tras un salto forzado: allí sigue abriendo la página siguiente, y 'auto' o 'bottom' pueden ocupar el pie de la página que lo cita. Colocación de figuras →

Error frecuente

::resource{id="…"} solo admite comillas dobles

Una inserción de bloque solo se reconoce como ::resource{id="…"} con comillas dobles; cualquier otra forma se queda en el texto como una línea visible. Figuras justo aquí →

Error frecuente

Sin <marker> ni filtros en los SVG, o pasan a mapa de bits

Una figura SVG solo sigue siendo vectorial en el PDF sin <marker>, filtros ni máscaras; si no, pasa a mapa de bits, y los filtros muy anidados pueden dejarla en blanco en Chrome. Dibuja las puntas de flecha como trazados. Figuras y tablas como recursos →

Comprobación del Sandbox · unknownResourceId

Recurso desconocido

Por qué. Un :ref o un ::resource usa un id que no corresponde a ningún recurso; la referencia imprime «?» y no se coloca nada.

Solución. Corrige el id (solo con comillas dobles) o añade el recurso. Documentación →

Créditos

Texto
Texto original, CC BY 4.0
Imágenes
  • Figura 2.1: un valle fluvial en V y un valle glaciar en U · Generated With Diffusion Models · original
  • Figura 2.2: perfil longitudinal de un glaciar de valle · Generated With Diffusion Models · original
  • Figura 2.3: un circo glaciar en sección · Generated With Diffusion Models · original
  • Figura 2.4: abrasión en la base del hielo · Generated With Diffusion Models · original
  • Figura 2.5: arranque en un resalte rocoso · Generated With Diffusion Models · original
  • Figura 2.6: una roca aborregada · Generated With Diffusion Models · original
  • Figura 2.7: morrenas laterales, central y frontal en planta · Generated With Diffusion Models · original
Fuentes
Faustina (SIL OFL 1.1) · Montserrat (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1)
Sandbox