Saltar al contingut principal
Recepta número 12

Receptari · Capítol 10 · Sortida i integració

D'una cadena Markdown a una pàgina dissenyada

Una cadena Markdown amb frontmatter es compon en pàgines de revista a dues columnes i es pinta en canvas, amb sis colors en lloc del blau per defecte.

En aquesta pàgina
Sortida
Canvas
Nivell
Intermedi
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.34.0
Llicència
Actualitzada el 16 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 180 × 240 mm
  • 2 columnes, espai entre columnes de 6 mm
  • Newsreader 9,5/13,5
  • Inter Tight
  • Young Serif
  • 2 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 58 ms
  • 176 línies de codi

En poques paraules

Les dues primeres pàgines d'un reportatge de viatges en una revista petita, amb una banda de color i un dibuix. Ensenya com un text senzill amb uns quants títols es converteix en una pàgina dissenyada amb els teus colors.

Què compondràs

Les primeres pàgines d'un reportatge de viatges en una revista petita, Quadern de camp. La pàgina 1 és una obertura en pàgina senar: una fotografia de salines i una duna al vespre que ocupa el 58 % superior, el títol en Young Serif de 54 punts i, a sota, dues columnes justificades que arrenquen amb una frase en negreta. La pàgina 2, al revers, continua sota una capçalera en majúscules espaiades i acaba amb un signe de fi i un colofó. Tot el disseny cap en una funció de configuració i una paleta de sis colors. El titular surt del títol de primer nivell, i l'entradeta, l'autora i la data, del frontmatter del Markdown, de manera que el mateix pen compon qualsevol article amb un títol que càpiga en dues línies; només la fotografia és pròpia d'aquest.

Aquesta recepta respon a

  • Com evito que els títols, les negretes i les vinyetes surtin en blau?
  • Com preparo una pàgina de llibre: format, marges interior i exterior simètrics, dues columnes i espai entre columnes?
  • Com converteixo una cadena Markdown en pàgines compostes i en dibuixo una en un canvas?

La resposta curta

script.js · línies 125–164al codi complet
const config = () => ({
  locale: t({ en: 'en-us', es: 'es', pt: 'pt', fr: 'fr', de: 'de', it: 'it' }), // the hyphenation
  colorPalette: colorPalette(),
  page: { // mirror: left is the inner margin and right the outer one; versos swap them
    width: mm(PAGE.width), height: mm(PAGE.height),
    margins: { top: mm(MARGIN.top), bottom: mm(MARGIN.bottom), left: mm(MARGIN.inner),
      right: mm(MARGIN.outer), mirror: true },
  },
  // 'double' is the default, stated so that the whole page setup reads in one place
  layout: { layoutType: 'double', gutterWidth: mm(6) },
  bodyText: { // justified, hyphenated and broken by paragraph: all on by default
    fontFamily: 'Newsreader', // one family name: there is no fallback chain
    fontSize: pt(9.5), lineHeight: pt(LEAD), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    firstLineIndent: mm(4), indentAfterHeading: false,
    // Optional, for 70 mm columns: word spaces from 0.8 to 1.8 × the normal one, and runts
    // tightened by at most 4 thousandths of an em, so the grey of the text stays even.
    minWordSpacing: 0.8, maxWordSpacing: 1.8, maxRuntTracking: 4,
  },
  headings: {
    fontFamily: 'Young Serif', fontWeight: 400, color: col('band'), // it has one weight
    levels: [
      // span: 'page' opens the H1 on a new page, across both columns. Parity 'odd' puts the
      // next article pasted in on a recto, with a blank verso only when one is needed.
      { level: 1, span: 'page', breakBefore: { enabled: true, parity: 'odd' },
        advancedDesign: opener() },
      // A line of margin and a line and a half of head: 2.5 lines, which snapToGrid (on by
      // default) rounds up to 3, so the text below lands back on the grid.
      { level: 2, fontSize: pt(13), lineHeight: pt(1.5 * LEAD), marginTop: pt(LEAD),
        marginBottom: pt(0) },
    ],
  },
  unorderedLists: { color: col('ink'), fontWeight: 400, bulletChar: '–',
    marginTop: pt(0), marginBottom: pt(0) },
  calloutStyles: [colophon()],
  header: header(),
  footer: footer(),
  // The magazine's name is its masthead, the same on every story (#849).
  checks: { contentInConfig: { allow: [MAGAZINE] } },
});

Ingredients

Tipografia
Newsreader, Young Serif, Inter Tight (SIL OFL 1.1)
Recursos
  • salt-road-1440.jpg
  • The salt pans and the dune at dusk on the opener, a photograph (Generated With Diffusion Models, original)

Elaboració

#1 · Totes les fonts, abans de la primera composició

script.js · línies 226–230al codi complet
const FONTS = {
  Newsreader: ['400', '400i', '700'], // text
  'Young Serif': ['400'], // display: it ships one weight, so the headings ask for 400
  'Inter Tight': ['400', '600'], // labels: kicker, byline, running heads, colophon
};

Postext mesura el text amb les fonts que el navegador té quan es compon, de manera que una composició que s'avancés a les fonts conservaria els talls de línia d'una font de reserva. buildDocumentWithFonts carrega abans de la primera composició totes les fonts que indica la configuració i les de FONTS; kitFonts(FONTS) li dona els fitxers de Fontsource, els mateixos que incrustaria un PDF. Després repassa les fonts que fan servir les pàgines, carrega les que faltin i torna a compondre. Una font que Fontsource no té es queda en la de reserva i surt a doc.contentWarnings com a fontFallback. Les negretes i cursives d'una font de text només es carreguen si la família les inclou.

#2 · Anomena els colors i apunta als noms

script.js · línies 23–41al codi complet
const palette = {
  ink: '#1b1e23', // text: a cool near-black, never #000
  band: '#2b3a67', // the one accent (an indigo): the folios, the subheads, the end mark
  sand: '#e9dcc0', // the kicker, the title and the byline
  salt: '#f7f4ee', // the standfirst
  rule: '#d6d3cc', // the hairline over the colophon
  muted: '#66686e', // running heads and the colophon
};
// Each colour carries its palette id and its hex. The design objects below are functions
// that config() calls, so col() copies the hex out of `palette` on every build: one edit
// to `palette` reaches the text, the folios and the drop folio alike.
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 (headings, bold, italic, bullets, the default running head) link
  // to 'main-color': point it at the accent, so nothing left unset prints blue.
  { id: 'main-color', name: 'defaults', value: { hex: palette.band, model: 'hex' } },
];

Cada color de la configuració és col('id'), un identificador de la paleta amb el seu valor hexadecimal al costat. bodyText.boldColor, italicColor, referenceColor i unorderedLists.color apunten a ink, i headings.color, a l'accent. Els valors per defecte del motor per a títols, negretes, cursives i pics estan enllaçats a main-color, i aquesta paleta dona a aquesta entrada el color de l'accent, de manera que qualsevol d'ells que no fixis surt anyil i no blau. Els objectes de disseny són funcions que config() crida a cada composició, i col() copia cada vegada el valor vigent de palette, així que un sol canvi a palette arriba igualment al text, als folis i a l'obertura. El signe de fi és una mostra de color en línia que fa referència a band, així que també canvia amb la paleta. La capçalera per defecte també està enllaçada a main-color, així que sortiria en el color de l'accent fins que la substitueixis (pas 5).

#3 · Una fotografia retallada al seu marc

script.js · línies 45–51al codi complet
// A JPEG in assets/, cut to PAGE.width × BAND (180 × 140 mm) and declared at its pixels, so at
// full width it fills the band exactly. A deeper band needs a picture cut to the new frame.
const landscape = { id: 'landscape', typeId: 'figure', kind: 'bitmap', createdAt: 0,
  updatedAt: 0, bitmap: { fileId: 'salt-road-1440.jpg', format: 'jpeg', width: 1440,
    height: 1120 },
  altText: 'Salt pans at dusk, a dune with a cairn of white stones on its crest, and a line of '
    + 'footprints crossing the pans towards it.' };

Les salines, la duna i la fita són una fotografia generada amb models de difusió, presa al vespre perquè el títol clar es llegeixi sobre un cel fosc. El JPEG està retallat al marc de la banda, PAGE.width × BAND mil·límetres, i el recurs declara els seus píxels, 1440 × 1120, de manera que a tota l'amplada la foto omple exactament la banda. Si la banda creix, cal una foto retallada al nou marc. L'obertura la mostra amb un element d'imatge que fa referència al recurs pel seu identificador.

#4 · El frontmatter escriu l'obertura

script.js · línies 55–91al codi complet
const BAND = 140; // mm from the top edge: the band holds the top 58% of the page
const TITLE_W = 130; // mm: room for two lines of the title; a third would push the byline
// down onto the pale salt pans: keep titles short
const DECK_W = 104; // mm: the standfirst stops short of the dune and its cairn
const MAGAZINE = t({ en: 'Field notes', es: 'Cuaderno de campo', pt: 'Caderno de campo',
  fr: 'Carnet de terrain', de: 'Unterwegs', it: 'Quaderno di campo' });
const label = { fontFamily: 'Inter Tight', fontSize: pt(7.5), fontWeight: 600,
  letterSpacing: pt(1.4), textTransform: 'uppercase' };
const below = (id, y, width) => ({ anchor: { to: `#${id}`, edge: 'below' },
  offset: { y: mm(y) }, ...(width && { size: { width: mm(width) } }) });
const opener = () => ({
  enabled: true,
  minHeight: mm(BAND - MARGIN.top + 5), // from the top margin to the band's foot, plus 5 mm
  slot: {
    elements: [
      // The photograph is PAGE.width × BAND (see art): at full width it fills the band.
      { kind: 'image', id: 'art', resourceId: 'landscape',
        placement: { anchor: { to: 'bleed', edge: 'top-left' }, size: { width: 'fill' } } },
      { kind: 'text', id: 'kicker', content: MAGAZINE, ...label, color: col('sand'),
        placement: { anchor: { to: 'page', edge: 'top-left' }, // recto: inner on the left
          offset: { x: mm(MARGIN.inner), y: mm(20) } } },
      // {titleText} is the H1; {subtitle}, {author} and {publishDate} are frontmatter. A bare
      // lineHeight multiplies the text's size: 1 sets the title solid. Both texts wrap.
      { kind: 'text', id: 'title', content: '{titleText}', fontFamily: 'Young Serif',
        fontSize: pt(54), lineHeight: 1, color: col('sand'), align: 'left',
        placement: below('kicker', 3, TITLE_W) },
      { kind: 'text', id: 'deck', content: '{subtitle}', fontFamily: 'Newsreader',
        fontSize: pt(12), lineHeight: 1.3, italic: true, color: col('salt'), align: 'left',
        placement: below('title', 5, DECK_W) },
      { kind: 'text', id: 'byline', ...label, color: col('sand'),
        content: t({ en: 'By {author} · {publishDate}',
          es: 'Por {author} · {publishDate}', pt: 'Por {author} · {publishDate}',
          fr: 'Par {author} · {publishDate}', de: 'Von {author} · {publishDate}', it: 'Di {author} · {publishDate}' }),
        placement: below('deck', 4.5) },
    ],
  },
});

El títol de primer nivell abasta les dues columnes, i la seva obertura és una zona de disseny: la fotografia a sang i quatre textos encadenats l'un sota l'altre. Un títol més llarg empeny cap avall l'entradeta i la signatura en lloc de superposar-s'hi, però a partir de la tercera línia la signatura cau sobre les salines clares. {titleText} és el text del títol; {subtitle}, {author} i {publishDate} surten del frontmatter. La \\ del títol talla la línia on la posis (salts de línia en els títols). minHeight es compta des del marge superior, així que l'alçada reservada acaba 5 mm per sota de la banda.

#5 · Capçaleres en lloc del blau per defecte

script.js · línies 95–114al codi complet
const HEAD = 12; // mm: the running heads from the top edge, the drop folio from the foot
const GAP = 3; // mm between a folio and its label, however many digits the folio has
const head = (id, content, parity, placement, color = col('muted')) => ({
  kind: 'text', id, content, parity, pages: 'body', ...label, color, placement,
});
const outer = (edge, x) => ({ anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(HEAD) } });
const beside = (id, edge, x) => ({ anchor: { to: `#${id}`, edge }, offset: { x: mm(x) } });
const header = () => ({
  elements: [ // folios on the outer margin's edge; each label hangs off its folio
    head('verso-folio', '{pageNumber}', 'even', outer('top-left', MARGIN.outer), col('band')),
    head('verso-title', '{title}', 'even', beside('verso-folio', 'right-of', GAP)),
    head('recto-folio', '{pageNumber}', 'odd', outer('top-right', -MARGIN.outer), col('band')),
    head('recto-title', MAGAZINE, 'odd', beside('recto-folio', 'left-of', -GAP)),
  ],
});
const footer = () => ({
  elements: [{ kind: 'text', id: 'drop-folio', content: '{pageNumber}', pages: 'opener',
    ...label, color: col('band'),
    placement: { anchor: { to: 'page', edge: 'bottom' }, offset: { y: mm(-HEAD) } } }],
});

Si omets header, torna la capçalera per defecte del motor: Open Sans sobre un filet de banda a banda, a totes les pàgines. Aquí cada foli s'ancora a la pàgina física i es filtra per paritat, de manera que sempre queda a la vora exterior. El text que l'acompanya s'ancora al foli, a GAP mil·límetres, amb right-of o left-of, i un foli de tres o quatre xifres el desplaça en lloc de xocar-hi. pages: 'body' deixa els quatre elements fora de l'obertura. El peu de pàgina porta un únic foli, el de l'obertura, i com que footer està definit, les altres pàgines perden el foli centrat per defecte.

#6 · Compon amb una configuració nova i pinta

script.js · línies 235–245al codi complet
await loadImage(landscape.bitmap.fileId, asset(landscape.bitmap.fileId));
const doc = await buildDocumentWithFonts({ markdown, resources }, config(), kitFonts(FONTS));
// showPages paints each page with renderPageToCanvas(page, doc, canvas, { scale }).
showPages(doc, {
  title: t({ en: 'From a Markdown string to a designed page',
    es: 'De una cadena Markdown a una página diseñada',
    pt: 'De uma string Markdown a uma página diagramada',
    fr: 'D’une chaîne Markdown à une page mise en forme',
    de: 'Von einem Markdown-String zur gestalteten Seite',
    it: 'Da una stringa Markdown a una pagina progettata' }),
});

config() és una funció perquè cada composició llegeixi la paleta tal com està: torna a cridar les funcions de disseny del pas 2. També valdria un únic objecte de configuració modificat al seu lloc: des de postext 1.25 el motor veu el canvi a la composició següent. buildDocumentWithFonts rep el contingut, aquesta configuració i les opcions de fonts del kit, i torna el document. showPages col·loca les pàgines com anirien en un llibre enquadernat, amb la pàgina 1 sola a la dreta, i pinta cadascuna amb renderPageToCanvas.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 012 · From a Markdown string to a designed page ══════════
// https://postext.dev/en/cookbook/first-page-from-markdown
// Code: MIT · Text: original (CC BY 4.0) · Photo: diffusion models
// Fonts: Newsreader, Young Serif, Inter Tight (SIL OFL 1.1) · Needs postext ≥ 1.34.0
//
// This pen sets a Markdown string with a frontmatter block on two magazine pages and paints
// them on canvases. The whole design is in config(); swap config() for {} in the build
// below to see the engine's defaults.
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';

const LANG = 'es'; // @lang: the sample document's language ('en' | 'es' | 'pt' | 'fr' | 'de' | 'it')
const RECIPE = 'first-page-from-markdown';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Every setting that shapes the pages is in this part, from PAGE down to config().
const PAGE = { width: 180, height: 240 }; // mm: a 3:4 magazine page
const MARGIN = { top: 22, bottom: 22, inner: 20, outer: 14 }; // mm; inner is the spine side
const LEAD = 13.5; // pt: the body leading, the grid every vertical space steps on

// #region palette: six named colours; every colour in the config links to one of them
const palette = {
  ink: '#1b1e23', // text: a cool near-black, never #000
  band: '#2b3a67', // the one accent (an indigo): the folios, the subheads, the end mark
  sand: '#e9dcc0', // the kicker, the title and the byline
  salt: '#f7f4ee', // the standfirst
  rule: '#d6d3cc', // the hairline over the colophon
  muted: '#66686e', // running heads and the colophon
};
// Each colour carries its palette id and its hex. The design objects below are functions
// that config() calls, so col() copies the hex out of `palette` on every build: one edit
// to `palette` reaches the text, the folios and the drop folio alike.
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 (headings, bold, italic, bullets, the default running head) link
  // to 'main-color': point it at the accent, so nothing left unset prints blue.
  { id: 'main-color', name: 'defaults', value: { hex: palette.band, model: 'hex' } },
];
// #endregion

// #region art: a photograph of the salt pans and the dunes at Sorra, cut for a page × band frame
// A JPEG in assets/, cut to PAGE.width × BAND (180 × 140 mm) and declared at its pixels, so at
// full width it fills the band exactly. A deeper band needs a picture cut to the new frame.
const landscape = { id: 'landscape', typeId: 'figure', kind: 'bitmap', createdAt: 0,
  updatedAt: 0, bitmap: { fileId: 'salt-road-1440.jpg', format: 'jpeg', width: 1440,

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

#Mira què substitueix la configuració

Compon amb una configuració buida i el mateix Markdown surt en una pàgina de 17 × 24 cm, en EB Garamond de 8 punts, amb títols blaus en Open Sans i una capçalera blava sobre un filet; el motor carrega també aquestes dues famílies, perquè la configuració per defecte les fa servir.

-const doc = await buildDocumentWithFonts({ markdown, resources }, config(), kitFonts(FONTS));
+const doc = await buildDocumentWithFonts({ markdown, resources }, {}, kitFonts(FONTS));

#Canvia el color de tota la pàgina

Canvia l'accent i la següent execució pinta amb el nou color els folis, els subtítols i el signe de fi, perquè col() copia el nou valor al costat de l'identificador cada vegada que es crida config(). La fotografia conserva els seus colors.

-  band: '#2b3a67', // the one accent (an indigo): the folios, the subheads, the end mark
+  band: '#3f5b3a', // the one accent (a pine green): the folios, the subheads, the end mark

#Pinta una pàgina en el teu propi canvas

renderPageToCanvas dona al canvas la mida de la pàgina en píxels a la resolució del document (300 ppp per defecte) multiplicada per scale, així que scale: 0.5 pinta a uns 150 ppp, i el CSS decideix com de gran es veu a la pantalla.

-showPages(doc, {
-  title: t({ en: 'From a Markdown string to a designed page',
-    es: 'De una cadena Markdown a una página diseñada',
-    pt: 'De uma string Markdown a uma página diagramada',
-    fr: 'D’une chaîne Markdown à une page mise en forme',
-    de: 'Von einem Markdown-String zur gestalteten Seite',
-    it: 'Da una stringa Markdown a una pagina progettata' }),
-});
+const canvas = document.body.appendChild(document.createElement('canvas'));
+renderPageToCanvas(doc.pages[0], doc, canvas, { scale: 0.5 });

Errors freqüents

  • Young Serif només té un gruix. Els títols van en negreta per defecte, així que aquí headings.fontWeight: 400 és obligatori: sense això, els títols demanen una Young Serif negreta que Fontsource no té, el navegador engruixeix la normal i doc.contentWarnings anota la font com a fontFallback.

Crèdits

Text
Text original, CC BY 4.0
Imatges
  • The salt pans and the dune at dusk on the opener, a photograph · Generated With Diffusion Models · original
Fonts
Newsreader (SIL OFL 1.1) · Young Serif (SIL OFL 1.1) · Inter Tight (SIL OFL 1.1)
Sandbox