Em poucas palavras
Um capítulo de um livro de física com uma coluna larga de texto e outra estreita junto à borda externa. A coluna estreita traz diagramas e notas curtas ao lado do texto a que se referem.
O que você vai compor
O capítulo 4 de Lever and Lens, um livro didático de física introdutória numa página de 210 × 275 mm. O texto corrido ocupa uma coluna larga e nunca entra na margem externa, um canal de 53 mm. O número do capítulo, um 4 verde, fica nesse canal na altura do título, e os objetivos de aprendizagem vêm embaixo. Os diagramas de raios se empilham a partir da cabeça do canal, e os termos-chave vão em glosas verde-menta ao lado dos trechos que os definem. As figuras que ficam na coluna de texto, sobre chapas escuras ou claras, têm as legendas na margem, na altura do pé da figura. Só o painel do prisma atravessa as duas colunas. As margens são espelhadas, por isso o canal fica no lado do corte de todas as páginas, à direita numa ímpar e à esquerda numa par.
Esta receita responde a
- Como monto uma diagramação em coluna e meia, com uma coluna de texto larga e uma coluna lateral estreita?
- Como coloco notas de margem ou glosas ao lado do parágrafo que elas explicam?
- Como acrescento uma figura com legenda numerada e a cito no texto (“ver fig. 3.2”)?
- Como decido onde vai uma figura: no alto da página, sobre as duas colunas, exatamente aqui ou na margem?
- Como coloco a legenda ao lado de uma figura, ou acima de uma tabela em uma barra de legenda?
- Como numero os títulos (1, 1.1, 1.1.1) e dou a cada nível um estilo diferente?
A resposta curta
const layout = {
layoutType: 'oneAndHalf', // a wide main column and a narrow side column
sideColumnPercent: 30, // of the 176 mm content width: a 52.8 mm channel
sideColumnRole: 'floats', // no body text: side figures, side captions and side boxes only
sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
gutterWidth: mm(7), // the text column keeps the rest: 176 − 52.8 − 7 = 116 mm
};
// A figure placed with span 'side' stacks in the channel from the head of the page that cites it,
// under the numeral on a chapter's first page.
const side = { span: 'side' };
// A figure left in the text column (the default span) sets its caption in the channel beside
// it; page-wide floats ignore captionSide and keep theirs underneath.
const resourceTypes = defaultResourceTypes(LANG).map((type) => (type.id !== 'figure' ? type
: { ...type, defaultPlacement: { captionSide: true } })); // the built-in types, in LANG
// A box fenced :::callout{type="term" span="side"} leaves the flow and lands in the channel at the
// height the text has reached: fence each gloss before the paragraph it should stand beside.
Ingredientes
- Funcionalidades
- Coluna de margem para flutuantesLegendas lateraisNotas na margemColuna e meiaMargens espelhadasCitações que posicionam as figurasPosicionamento de figurasLegendas numeradasFiguras e tabelas como recursosFigura e Tabela no seu idiomaAberturas desenhadasAncoragem de elementos de designAtributos de títuloTítulos numeradosEstilos de títuloCapítulos que abrem em página ímparBoxesCabeços e fóliosCabeços por tipo de páginaPaleta de cores semântica
- Também usa
- Estilos de parágrafoTipos de recurso personalizadosSobrescritos e subscritosCapítulos sem número
- Tipografia
- Merriweather, Merriweather Sans (SIL OFL 1.1)
- Materiais
- Nenhum: todas as imagens são desenhadas em código
Preparo
#1 · Entregar a margem aos flutuantes
O código deste passo é a resposta curta acima. Numa diagramação em coluna e meia, sideColumnPercent: 30 dá à coluna lateral 30% dos 176 mm de largura da mancha (52,8 mm), e a coluna de texto fica com o que sobra depois da medianiz de 7 mm (116 mm, uns 75 caracteres de Merriweather de 9,3 pt). sideColumnRole: 'floats' mantém o texto corrido fora da coluna lateral, e sideColumnSide: 'outer' a põe no lado externo, que as margens espelhadas alternam de uma página para outra. As figuras vão para lá com span: 'side'. Um boxe com span="side" no bloco sai do fluxo e entra no canal na altura a que o texto chegou, por isso cada glosa começa na altura do bloco que vem depois dela.
#2 · Deixar a citação posicionar cada figura
const drawings = new Map(); // fileId → SVG markup, registered before the build
const figure = (id, { width, height, markup }, placement) => {
drawings.set(`${id}.svg`, markup);
return { id, typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0, caption: t(captions[id]),
altText: t(captions[id]), // read aloud in HTML and tagged PDF; the canvas does not use it
svg: { fileId: `${id}.svg`, width, height }, ...(placement && { placement }) };
};
const resources = [ // no placement: a main-column float, its caption in the channel
figure('burning-glass', burningGlass()),
figure('refraction', refraction(), side),
figure('critical-angle', criticalAngle(), side),
figure('fibre', fibre()),
figure('prism', prism(), { span: 'page', position: 'top' }), // across text column and channel
figure('principal-rays', principalRays()),
figure('diverging', diverging(), side),
];
O primeiro :ref a uma figura a numera e a coloca onde o posicionamento manda. Uma figura span: 'side' se empilha a partir da cabeça do canal na página que a cita, por mais abaixo que esteja a citação, e passa para a página seguinte quando o resto do canal é curto demais. As figuras 4.2 e 4.3, ambas citadas na página 88, descem pelo canal dessa página com a glosa do ângulo crítico entre elas. O prisma é um flutuante top na largura da página citado na página 88, e um flutuante nunca fica acima da citação, de modo que ele abre a página 89 sobre as duas colunas. As figuras 4.1, 4.4 e 4.6 ficam na coluna de texto e recebem captionSide do defaultPlacement do tipo figura. Elas ocupam o espaço de baixo da coluna, por isso cada legenda fica na altura do pé da figura; num espaço de cima, ela se alinharia com o topo da figura.
#3 · Abrir o capítulo na margem
// Every element counts toward the opener's depth, the page-anchored numeral too (gotcha:
// opener-reserves-anchored). minHeight fixes that depth at nine lines of the grid, room for a
// one-line title, the rule and a four-line standfirst (41.2 mm), so the text starts on the same
// line in every such chapter, however short its standfirst and even with a smaller numeral. Kicker
// and numeral (40.6 mm) reach the ninth line too; a deeper opener grows past it, line by line.
const [KICKER, NUMERAL] = [8, 104]; // pt
const opener = {
enabled: true,
minHeight: pt(LEAD * 9), // 42.9 mm: the text starts on the eleventh line, after marginBottom
slot: {
elements: [
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: SANS, fontWeight: 800,
fontSize: pt(32), lineHeight: 1.05, color: col('ink'), align: 'left', overflow: 'wrap',
placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill' } } },
{ kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(1), color: col('accent'),
placement: { anchor: { to: '#title', edge: 'below' }, offset: { y: mm(4) },
size: { width: 'fill' } } },
{ kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
fontSize: pt(10.5), lineHeight: 1.45, color: col('ink'), align: 'left', overflow: 'wrap',
placement: { anchor: { to: '#rule', edge: 'below' }, offset: { y: mm(3.5) },
size: { width: 'fill' } } },
// The kicker hangs from the page's top-right corner, not from the heading: the channel lies
// outside the heading's column, and on the right only on a recto (so chapters open on one).
// The numeral hangs from the kicker.
{ kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...label,
fontSize: pt(KICKER), align: 'left', placement: { anchor: { to: 'page', edge: 'top-right' },
offset: { x: mm(-OUTER), y: mm(TOP) }, size: { width: mm(CHANNEL) } } },
{ kind: 'text', id: 'numeral', content: '{chapterNumber}', fontFamily: SANS, fontWeight: 800,
fontSize: pt(NUMERAL), lineHeight: 1, color: col('accent'), align: 'left',
placement: { anchor: { to: '#kicker', edge: 'below' }, offset: { y: mm(0.5) },
size: { width: mm(CHANNEL) } } },
],
},
};
O título de nível 1 fica na coluna de texto, onde um slot de design empilha o texto, o fio e a linha fina; o antetítulo pende do canto superior direito da página, e o numeral pende do antetítulo, os dois com a largura do canal. minHeight fixa a abertura em nove linhas da grade (42,9 mm), o bastante para um título de uma linha, o fio e uma linha fina de quatro linhas, por isso uma linha fina mais curta não puxa o texto para cima. O antetítulo e o numeral de 104 pt terminam 40,6 mm abaixo da margem superior, dentro dessas nove linhas, de modo que também não empurram o texto para baixo. O canal só fica à direita numa página ímpar, por isso o H1 quebra para uma página ímpar. O boxe de objetivos vem depois do primeiro parágrafo, e nenhuma figura de margem é citada antes dele, de modo que ele fica sob o numeral (veja Erros comuns).
#4 · Manter os fólios na borda do canal
const [HEAD_Y, FOOT_Y, HEAD_GAP] = [12.5, -12, 9]; // mm from the top and bottom trim; folio to head
// A text on the physical page: edge picks the corner, x and y are its offsets in mm.
const head = ({ edge, x, y = HEAD_Y, ...text }) => ({
kind: 'text', pages: 'body', ...label, color: col('muted'), ...text,
placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(y) } },
});
const folio = { content: '{pageNumber}', fontSize: pt(8.5), letterSpacing: pt(0),
color: col('accent') };
const verso = { parity: 'even', edge: 'top-left' }; // x counts in from the left edge
const recto = { parity: 'odd', edge: 'top-right' }; // x counts back from the right edge
const header = { elements: [
head({ id: 'verso-folio', ...verso, ...folio, x: OUTER }),
head({ id: 'verso-title', ...verso, content: '{title}', x: OUTER + HEAD_GAP }),
head({ id: 'recto-title', ...recto, x: -(OUTER + HEAD_GAP),
content: t({ en: 'Chapter {chapterNumber} · {chapterTitle}',
es: 'Capítulo {chapterNumber} · {chapterTitle}' }) }),
head({ id: 'recto-folio', ...recto, ...folio, x: -OUTER }),
] };
// A chapter's first page, always a recto, carries a drop folio at the foot of the channel instead.
const footer = { elements: [
head({ id: 'drop-folio', ...recto, ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,
y: FOOT_Y }),
] };
Cada elemento é ancorado na página física e filtrado por parity, por isso fólio e cabeço ficam na mesma borda que o canal nos dois lados da página dupla. pages: 'body' os deixa fora da abertura, que recebe no lugar um fólio no pé do canal.
#5 · Começar o livro no capítulo 4
const continuation = { pageNumbering: { startAt: 87 }, // odd, like page 1: a recto
headings: { h1: 3, h2: 0, h3: 0, h4: 0, h5: 0, h6: 0 } }; // the next # is chapter 4
const doc = await buildDocumentWithFonts({ markdown, resources, continuation }, config(),
kitFonts(FONTS));
showPages(doc, { title: t({ en: 'Textbook with a margin column',
es: 'Libro de texto con columna al margen' }) });
Estas páginas são o capítulo 4 de um livro mais longo. A continuação põe o contador de capítulos em 3, de modo que {chapterNumber} imprime 4 e o numberingTemplate: '{1}.{2}' do nível 2 numera as seções de 4.1 a 4.3; as figuras vão de 4.1 a 4.7. ## Questions {style="plain"} usa uma entrada de headingStyles com numbered: false, por isso esse título não tem número. Os fólios começam em 87 porque a primeira página é ímpar, e uma página ímpar leva fólio ímpar.
#6 · Dar nome às cores uma vez só
const palette = {
ink: '#1a222d', // text, and the dark panels of figures 4.1, 4.4 and 4.5
accent: '#17774f', // the only accent colour: numerals, folios, section headings, labels
ray: '#f2a516', // light rays in every diagram
glass: '#cfe6dd', // glass in the diagrams
tint: '#edf5f1', // the key-term glosses and the light plate of a construction diagram
muted: '#5b6863', // running heads, the normals in the diagrams, the colophon
paper: '#ffffff',
};
// A colour carries its id and its hex. The diagrams read `palette` as well, so retint the
// chapter by editing it: the text, the designs and the drawings change together.
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' } },
];
Cada cor da configuração está ligada a uma entrada da paleta e também carrega o hex, que col() copia do mesmo objeto. Para mudar as cores do capítulo, edite palette: os diagramas leem o mesmo objeto, por isso o vidro, os raios, os painéis escuros e a chapa clara mudam junto com os numerais, os rótulos e as glosas. main-color aponta para a cor de destaque, de modo que qualquer cor padrão dos estilos de texto que a configuração deixa sem definir sai em verde, não no azul do motor.
A receita completa
// ═══ Postext Cookbook · Nº 001 · Textbook with a margin column ═══════════════════
// https://postext.dev/en/cookbook/textbook-margin-column
// Code: MIT · Text: original (CC BY 4.0) · Diagrams: generated in code (CC BY 4.0)
// Fonts: Merriweather, Merriweather Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A chapter of a physics textbook in the column-and-a-half layout: the body text keeps to
// the main column, and the outer margin is a channel for diagrams, captions and glosses.
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, defaultResourceTypes,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'textbook-margin-column';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: semantic colours, each linked by id and written out in hex
const palette = {
ink: '#1a222d', // text, and the dark panels of figures 4.1, 4.4 and 4.5
accent: '#17774f', // the only accent colour: numerals, folios, section headings, labels
ray: '#f2a516', // light rays in every diagram
glass: '#cfe6dd', // glass in the diagrams
tint: '#edf5f1', // the key-term glosses and the light plate of a construction diagram
muted: '#5b6863', // running heads, the normals in the diagrams, the colophon
paper: '#ffffff',
};
// A colour carries its id and its hex. The diagrams read `palette` as well, so retint the
// chapter by editing it: the text, the designs and the drawings change together.
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' } },
];
// #endregion
// The page in mm, named once: the channel, the opener and the running heads derive from it.
const [TRIM_W, TRIM_H] = [210, 275];
const [TOP, BOTTOM, INNER, OUTER] = [24, 22, 20, 14]; // inner and outer swap on a verso
const LEAD = 13.5; // body leading in pt
const [SERIF, SANS] = ['Merriweather', 'Merriweather Sans'];
// #region answer: a float-only channel on the outer edge, and what goes into it
const layout = {
layoutType: 'oneAndHalf', // a wide main column and a narrow side column
sideColumnPercent: 30, // of the 176 mm content width: a 52.8 mm channel
sideColumnRole: 'floats', // no body text: side figures, side captions and side boxes only
sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
gutterWidth: mm(7), // the text column keeps the rest: 176 − 52.8 − 7 = 116 mm
};
// A figure placed with span 'side' stacks in the channel from the head of the page that cites it,
O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)
Variações
#Manter as legendas sob as figuras
Com os padrões simples do tipo figura, as legendas das figuras 4.1, 4.4 e 4.6 tomam linhas da coluna de texto, e o canal só recebe diagramas e glosas.
-const resourceTypes = defaultResourceTypes(LANG).map((type) => (type.id !== 'figure' ? type
- : { ...type, defaultPlacement: { captionSide: true } })); // the built-in types, in LANG
+const resourceTypes = defaultResourceTypes(LANG); // what the engine uses when none are set#Pôr o canal à direita em todas as páginas
Para um documento lido uma página por vez na tela, pare de espelhar as margens e passe o fólio e o cabeço da página par para a borda direita; assim os capítulos podem abrir em qualquer página.
- sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
+ sideColumnSide: 'right', // what 'outer' means anyway once the margins stop mirroring
- bottom: mm(BOTTOM), left: mm(INNER), right: mm(OUTER), mirror: true } }, // left: recto's inner
+ bottom: mm(BOTTOM), left: mm(INNER), right: mm(OUTER), mirror: false } },
- { level: 1, breakBefore: { enabled: true, parity: 'odd' }, marginBottom: pt(LEAD),
+ { level: 1, breakBefore: { enabled: true, parity: 'any' }, marginBottom: pt(LEAD),
-const verso = { parity: 'even', edge: 'top-left' }; // x counts in from the left edge
+const verso = { parity: 'even', edge: 'top-right' };
- head({ id: 'verso-folio', ...verso, ...folio, x: OUTER }),
- head({ id: 'verso-title', ...verso, content: '{title}', x: OUTER + HEAD_GAP }),
+ head({ id: 'verso-folio', ...verso, ...folio, x: -OUTER }),
+ head({ id: 'verso-title', ...verso, content: '{title}', x: -(OUTER + HEAD_GAP) }),
- head({ id: 'drop-folio', ...recto, ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,
+ head({ id: 'drop-folio', ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,#Abrir o capítulo sob uma faixa de cor
Abertura de capítulo sobre uma faixa sangrada sangra uma faixa de cor no alto da página e compõe sobre ela o título e um número de capítulo de 168 pt.
Erros comuns
Erro comum
Boxes laterais nunca flutuam: esperam espaço
Um boxe com span: 'side' não flutua: fica ao lado do bloco que ele segue e, quando o canal da margem está cheio, espera a página seguinte. Coloque cada glosa logo depois do parágrafo que ela explica. Quando o capítulo termina com boxes ainda à espera, cada um ocupa a coluna lateral de uma página depois do texto, na ordem dos seus delimitadores, e a diagramação avisa (afterText); até o postext 1.24 só uma dessas páginas era aberta e os boxes restantes sumiam sem aviso. Notas na margem →
Erro comum
Um flutuante 'top' vai para a página seguinte à sua citação, a menos que possa encabeçar a página que o cita
Por padrão um flutuante nunca fica acima da própria referência, então um flutuante 'top' na largura da página citado na página N abre a página N+1. Com placement.citingPage: true no recurso ou no defaultPlacement do seu tipo (ou layout.floatsAtCitingPage para o livro todo, desde o postext 1.25) ele encabeça a página N, e o texto acima da referência desce para baixo dele, quando cabe dentro de layout.maxTopFraction e a linha que o cita continua nessa página. Nunca encabeça a primeira página de um capítulo nem uma página depois de uma quebra forçada: ali continua abrindo a página seguinte, e 'auto' ou 'bottom' podem ocupar o pé da página que o cita. Posicionamento de figuras →
Erro comum
Uma abertura reserva altura até o seu elemento ancorado mais baixo
Uma abertura com design avançado reserva a altura do seu elemento mais baixo, e os elementos ancorados à página ou à sangria abaixo do título também contam, então um ornamento no pé da página empurra o texto para a página seguinte. Dê a esse elemento reserve: false (desde o postext 1.5): ele é pintado onde está ancorado e não reserva nada. Os elementos que acompanham a própria faixa (ancorados ao pé dela, ou com altura 'fill') nunca definem a altura dela. Aberturas desenhadas →
Erro comum
Sem <marker> nem filtros na arte SVG (vira bitmap)
Uma figura SVG só continua vetorial no PDF sem <marker>, filtros e máscaras; caso contrário, é rasterizada, e filtros muito aninhados podem deixá-la em branco no Chrome. Desenhe as pontas de seta como caminhos (paths). Figuras e tabelas como recursos →
- Figuras e glosas se empilham no canal na ordem em que o texto chega a elas, nunca lado a lado. O bloco da glosa do ângulo crítico vem depois do parágrafo da lei de Snell e antes do parágrafo que cita a figura 4.3, por isso na página 88 ela fica entre as figuras 4.2 e 4.3, ao lado do parágrafo que apresenta o termo. Com o bloco depois dessa citação, ela cairia sob a figura 4.3.
- Na primeira página de um capítulo, as figuras laterais se empilham sob o antetítulo e o numeral. Uma figura citada no primeiro parágrafo ocupa esse lugar e empurra o boxe de objetivos canal abaixo, por isso este capítulo cita a primeira figura de margem depois do boxe.
Créditos
- Receita
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Fontes
- Merriweather (SIL OFL 1.1) · Merriweather Sans (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


