In short
Four pages of an atlas of made-up islands. It shows how to give maps their own numbers and how to turn a large map sideways so it fills a page.
What you'll build
The first sheet of an atlas of the Solan Isles, an archipelago invented for this recipe and drawn in code from one height field. Page 1 opens on a deep-sea blue band with the atlas's name at 56 pt and a compass rose, and Map 1, the relief of the whole group, fills the foot of the page. The north end of the main island and the plan of its harbour head the two columns of page 2. On page 3 the chart of the islands is turned a quarter so that its grid of 8 km squares fills the page. Page 4 holds the gazetteer, seventeen places in red discs with the chart square of each, and an imprint at the foot. Each map is captioned above the drawing on a blue bar, and Map 1's key is a line of swatches in the map's colours.
This recipe answers
- How do I add a figure with a numbered caption and cite it in the text ("see Fig. 3.2")?
- How do I control where a figure goes: top of page, across both columns, exactly here, or in the margin?
- How do I add colour-key swatches to text, captions or table notes?
The short answer
// Every caption stands above its drawing or table, in the label face. Maps count 1, 2, 3…
// through the atlas as a type of their own and set their caption on a bar in the band colour.
const captionStyle = { fontFamily: LABEL, fontSize: pt(9), labelColor: col('band'),
position: 'above', gap: mm(1.6), note: { fontSize: pt(7.8), color: col('muted') } };
const MAP_WORD = t({ en: 'Map', es: 'Mapa' });
const mapType = { id: 'map', name: MAP_WORD, shortLabel: MAP_WORD, captionPrefix: MAP_WORD,
numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal',
captionStyle: { backgroundEnabled: true, background: col('band'), color: col('paper'),
labelColor: col('paper'), padding: mm(1.4) } }; // the bar only; the rest is captionStyle's
// Each map floats from its first :ref to the first slot its placement allows.
const PLACEMENT = {
relief: { position: 'bottom', span: 'page' }, // the foot of the page that cites it
north: { position: 'top' }, // the head of the next free column
harbour: { position: 'top' },
chart: { rotate: 'ccw' }, // turned a quarter, top to the left, on a page of its own
};
// Drawing sizes in mm. Turned, the chart is laid out along 247.6 mm, the text area's 53 grid
// lines less one for the float gap; the bar and the note leave 182.2 mm of the 196 mm measure.
const MAP = { relief: [196, 136], north: [95, 88], harbour: [95, 88], chart: [247.6, 182.2] };
A Map type captioned on a bar above the drawing, and where each map goes
Ingredients
- Features
- Landscape tables and figuresColour swatchesCaption styleCustom resource typesNumbered captionsCitations that place figuresFigure placementSource and credit linesSemantic colour paletteDesigned openersFull-width chapter bandHeading attributesMirrored marginsTables from dataTable styleInline chipsRunning heads and foliosFigures and tables as resourcesPages on a canvas
- Also uses
- Heading stylesFigure and Table in your languagePaper colourHeads by page roleParagraph stylesRunning heads per section
- Type
- Marcellus, Alegreya Sans, Alegreya Sans SC (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · One palette for the page and the maps
const palette = {
ink: '#23282b', paper: '#fbfaf6', // a blue-black on a warm white
band: '#1f4a5c', // the accent: opener band, caption bars, table head, references
road: '#b2432f', // the second colour: roads, lights and the place numbers
muted: '#626a6d', rule: '#c8c2b4', // running heads and notes; hairlines
deep: '#8fb9c6', sea: '#cfe3e8', // the maps' water: over and under 20 m
land: '#efe6cf', hill1: '#d9c9a3', hill2: '#bfa97a', forest: '#7f9b6a', // and their land
};
// col(id) links a colour to its palette entry; the drawings read the same hex from `palette`.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.band }) // the defaults' id
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
The six map tints are keys of the same object as the page's colours, so colorPalette lists them as palette entries and the drawings take their SVG fills from palette[id]. Paper-white type on band, the blue of the opener, the caption bars and the table's header row, has a contrast of 9.2:1; road, the only red, is kept for roads, lights and place numbers and has 5.4:1 against the paper. main-color takes the hex of band, and the defaults link headings, caption bars and list markers to that id, so any of them the configuration leaves unset prints in the atlas's blue.
#2 · Where each map goes
The code is the short answer above. Map 1 is a bottom float because a page-wide top float never lands on the page that cites it. Maps 2 and 3 are top column floats cited on page 1, so they take the heads of the two columns of page 2 (Placement). rotate: 'ccw' puts the chart's top at the left edge and gives it page 3 to itself. Turned, the drawing runs 247.6 mm along the page, the text area's 53 grid lines less one for the float gap, and 182.2 mm across it, what is left of the 196 mm measure after the caption bar and the note. A taller drawing would be scaled down and leave bare paper at the head of the page.
#3 · A key drawn from the same ids
// The bands the maps are filled with, lowest first. Art and key share each palette id, so one hex
// changes both; the unit is spelled out once, since the small caps print an m as an M.
const RELIEF = [
{ id: 'deep', en: 'sea over 20', es: 'mar de más de 20' },
{ id: 'sea', from: -20, en: 'sea under 20', es: 'de menos de 20' },
{ id: 'land', from: 0, en: 'land to 50', es: 'tierra hasta 50' },
{ id: 'hill1', from: 50, en: '50–120', es: '50–120' },
{ id: 'hill2', from: 120, en: 'over 120', es: 'más de 120' },
{ id: 'forest', en: 'woodland', es: 'bosque' },
];
const legend = t({ en: 'In metres: ', es: 'En metros: ' }) // a thin space more after each swatch
+ RELIEF.map((band) => `:swatch{color="${band.id}"} \u2009${t(band)}`).join(' · ');
RELIEF lists the bands with their palette ids and the heights where they start. The art fills each band with palette[id] and the key under Map 1 writes a :swatch with the same id, so a new hex in the palette changes the drawing and the key at once. The key names the unit once, in words, because the note is set in Alegreya Sans SC, which prints a lowercase m as a small capital M. On page 2 the text puts the same swatches beside the two depths of water.
#4 · Maps are resources, numbered and placed by their citations
// A plan's key: a bare chip keeps each number on the line of its name, and the dot after it.
const key = (names) => names.map((name, i) => `:chip[${i + 1} ${name}${names[i + 1] ? ' ·' : ''}]`
+ '{style="key"}').join(' ');
const TEXTS = t({ // caption, the key under the drawing, and the alt text of each map
en: {
relief: ['The islands: relief and roads', `${legend} · roads in red, ferries dashed`,
'Relief map of Brannay, Orrin, Kellay and Skarra in sand and ochre on blue water, with '
+ 'red roads.'],
north: ['The north end of Brannay', 'Contour interval 25 metres; heights in metres above the '
+ 'sea. The red discs number the places of the gazetteer.', 'The Ward of Brannay, 234 m, in '
+ 'contours, with the Hool Stacks off its north-west point and the road round it to Tofts.'],
harbour: ['Kirkwick harbour', 'Soundings in metres at the lowest tide. '
+ key(['ferry pier and light', 'lifeboat station', 'harbour office', 'fish store', 'kirk']),
'Plan of Kirkwick: one street of houses on a narrow inlet, a pier into its mouth, depths '
+ 'from 2 to 15 m.'],
chart: ['The islands and their approaches, with the gazetteer’s grid', 'Squares of 8 '
+ 'kilometres, lettered west to east and numbered north to south.', 'Chart of the group '
+ 'and the mainland coast on a lettered grid, with the seventeen places in red discs.'],
table: ['Gazetteer of the numbered places', 'Squares are those of :ref{id="chart"}.'],
},
es: {
relief: ['Las islas: relieve y carreteras', `${legend} · carreteras en rojo, `
+ 'transbordadores a trazos', 'Relieve de Brannay, Orrin, Kellay y Skarra en tintas de '
+ 'arena y ocre sobre agua azul, con las carreteras en rojo.'],
north: ['El extremo norte de Brannay', 'Equidistancia de las curvas: 25 metros; alturas en '
+ 'metros sobre el mar. Los discos rojos numeran los lugares del nomenclátor.', 'El Ward '
+ 'of Brannay, de 234 m, en curvas de nivel, con los Hool Stacks frente a su punta noroeste '
+ 'y la carretera de Tofts.'],
harbour: ['El puerto de Kirkwick', 'Sondas en metros con la marea más baja. '
+ key(['muelle y luz', 'estación de salvamento', 'oficina del puerto', 'almacén de pescado',
'iglesia']), 'Plano de Kirkwick: una calle de casas junto a una ensenada estrecha, un '
+ 'muelle en su boca y fondos de 2 a 15 m.'],
chart: ['Las islas y sus accesos, con la cuadrícula del nomenclátor', 'Cuadros de 8 '
+ 'kilómetros, con letras de oeste a este y números de norte a sur.', 'Carta del grupo y de '
+ 'la costa de tierra firme en cuadros, con los diecisiete lugares en discos rojos.'],
table: ['Nomenclátor de los lugares numerados',
'Los cuadros son los del :ref{id="chart" case="lower"}.'],
},
});
const svgResource = (id, [w, h], more) => ({ id, typeId: 'map', kind: 'svg', createdAt: 0,
updatedAt: 0, svg: { fileId: `${id}.svg`, width: w * 10, height: h * 10 }, ...more });
const resources = [
...Object.keys(MAP).map((id) => svgResource(id, MAP[id], { placement: PLACEMENT[id],
caption: TEXTS[id][0], note: TEXTS[id][1], altText: TEXTS[id][2] })),
svgResource('rose', [ROSE, ROSE], { altText: t({ en: 'Compass rose',
es: 'Rosa de los vientos' }) }),
{ id: 'gazetteer', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
caption: TEXTS.table[0], note: TEXTS.table[1], placement: { position: 'top', span: 'page' },
table: { model: gazetteer() } },
];
const drawings = { relief: reliefMap, north: northMap, harbour: harbourMap, chart: chartMap };
for (const [id, draw] of Object.entries(drawings)) await loadSvg(`${id}.svg`, draw(MAP[id]));
await loadSvg('rose.svg', rose(ROSE)); // drawn by the opener, never cited, so never numbered
A resource takes its number from the text's first citation of it, and :ref{id="north"} prints the type's short label and that number, Map 2, in the running text or in a caption note. The chart and the gazetteer are first cited on page 2, in that order, so the chart takes page 3 and the gazetteer the head of page 4. The compass rose is a resource of the same type, but only the opener draws it and the text never cites it, so the maps still count from 1 to 4. Each entry of the harbour key is one chip with no fill, border or padding, so its number, its name and the dot after it stay on one line.
#5 · Numbers the maps and the gazetteer share
const CHART = { y0: -5, square: 8 }; // Map 4's grid: 8 km squares from its top-left corner
const PLACES = [ // name, what it is (en, es), island, x and y in km on the sheet, map mark
['Skarra', ['lighthouse', 'faro'], 'Skarra', 34.4, 5.4, 'light'],
['Hool Stacks', ['sea stacks', 'farallones'], 'Brannay', 22.8, 9],
['Kellay', ['gannet colony', 'colonia de alcatraces'], 'Kellay', 5.4, 10.6],
['Ward of Brannay', ['summit, 234 m', 'cumbre, 234 m'], 'Brannay', 26.38, 12.04, 'summit'],
['Hesta Ness', ['headland', 'cabo'], 'Brannay', 30.1, 15.9],
['Tofts', ['hamlet', 'aldea'], 'Brannay', 22.7, 14.9, 'village'],
['Kirkwick', ['village and ferry pier', 'pueblo y muelle'], 'Brannay', 28.3, 15, 'village'],
['St Brendan’s', ['ruined chapel', 'capilla en ruinas'], 'Brannay', 23.8, 21.6, 'chapel'],
['Brannay Sound', ['strait', 'estrecho'], '—', 25.6, 22.7],
['Scarfa Ness', ['headland', 'cabo'], 'Orrin', 36.3, 22.3],
['Carrick', ['mainland port', 'puerto de tierra firme'], '—', 59.4, 21.2, 'village'],
['Orrinsetter', ['hamlet', 'aldea'], 'Orrin', 31.7, 24.8, 'village'],
['Housa Stone', ['standing stone', 'menhir'], 'Orrin', 29.4, 25.6, 'stone'],
['Leury Sands', ['beach', 'playa'], 'Brannay', 10.9, 25.6],
['Holm of Orrin', ['islet', 'islote'], 'Orrin', 37.74, 28.4],
['Pollwick', ['bay', 'bahía'], 'Orrin', 32.4, 28.3],
['Tang Skerry', ['rock and beacon', 'roca y baliza'], '—', 25.08, 28.88, 'light'],
].map(([name, [en, es], island, x, y, mark]) => ({ name, kind: t({ en, es }), island, x, y, mark }))
.sort((a, b) => a.y - b.y).map((place, i) => ({ ...place, no: i + 1 }));
const square = ({ x, y }) => 'ABCDEFGH'[Math.floor(x / CHART.square)]
+ (Math.floor((y - CHART.y0) / CHART.square) + 1); // the square the place falls in
function gazetteer() {
const heads = t({ en: ['No.', 'Place', 'What it is', 'Island', 'Square'],
es: ['N.º', 'Lugar', 'Qué es', 'Isla', 'Cuadro'] });
const cells = (row, isHeader = false) => row.map((content) => ({ content, isHeader }));
let m = { headerRowCount: 1, columnWidths: [8, 34, 42, 18, 12], rows: [cells(heads, true),
...PLACES.map((p) => cells([`:chip[${p.no}]{style="no"}`, `**${p.name}**`, p.kind, p.island,
square(p)]))] };
for (let row = 0; row < m.rows.length; row++) {
for (const c of [0, 4]) m = setAlignment(m, { row, col: c }, 'center');
}
return m; // the zebra rows are the table style's: tableStyle.bodyAlternateBackground
}
PLACES is sorted from north to south and numbered in that order, and the maps print the numbers in red discs and the table in red chips. square() works out the chart square from the same kilometre coordinates that place each mark on the maps, so Kirkwick, number 6, is in D3 on the chart and in the table. Every second row takes its pale blue from the table style: bodyAlternateBackgroundEnabled, with bodyAlternateBackground linked to sea.
#6 · The atlas's name on a band of its own blue
const BAND = 80; // mm from the trim to the foot of the band
const AIR = 7; // mm at least between the band and the first line of text
const ROSE = 50; // mm across the compass rose
const pin = (to, edge, x, y, size) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) },
...(size && { size }) }); // to: 'page', 'bleed' or '#id' of an element listed before
const text = (id, content, family, size, color, placement, extra) => ({ kind: 'text', id,
content, fontFamily: family, fontSize: pt(size), color: col(color), align: 'left',
overflow: 'wrap', placement, ...extra }); // a long running head wraps too, never '…'
const opener = { enabled: true,
// The band reserves down to its foot; minHeight adds AIR, in whole grid lines.
minHeight: pt(LEAD * Math.ceil((BAND + AIR - PAGE.top) / (LEAD * PT))),
slot: { elements: [ // array order is paint order
{ kind: 'box', id: 'band', style: { backgroundColor: col('band') },
placement: pin('bleed', 'top-left', 0, 0, { height: mm(BAND) }) }, // no width: edge to edge
{ kind: 'image', id: 'rose', resourceId: 'rose', // page 1 is a recto: the fore-edge is right
placement: pin('page', 'top-right', -PAGE.outer, (BAND - ROSE) / 2, { width: mm(ROSE),
height: mm(ROSE) }) },
text('kicker', '{attr.sheet} · {titleText}', LABEL, 9.5, 'sea', pin('page', 'top-left',
PAGE.inner, 23), { fontWeight: 500, letterSpacing: pt(1.4) }),
text('title', '{title}', DISPLAY, 56, 'paper', pin('#kicker', 'below', -1, 2),
{ lineHeight: 1 }),
text('lead', '{attr.lead}', TEXT, 10.5, 'sea', pin('#title', 'below', 1, 3,
{ width: mm(128) }), { italic: true, lineHeight: 1.35 }),
] } }; // hook-up: headings.levels[0] = { span: 'page', breakBefore, advancedDesign: opener }
The band is a box anchored to 'bleed' and given no width, so it runs from edge to edge. The large title is {title}, the atlas's name from the frontmatter, and the heading's own text follows the sheet number in the kicker. On its own the band reserves space down to its foot, and the text would start 3.9 mm under it; minHeight raises the reservation to 14 grid lines below the top margin, which starts the text 8.7 mm under the band.
The whole recipe
// ═══ Postext Cookbook · Nº 067 · Atlas sheet: numbered maps and a rotated overview ═════
// https://postext.dev/en/cookbook/atlas-map-sheet
// Code: MIT · Text: original (CC BY 4.0) · Maps: generated in code from seed 1874 (CC BY 4.0)
// Fonts: Marcellus, Alegreya Sans, Alegreya Sans SC (SIL OFL 1.1) · Needs postext ≥ 1.34.0
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, defaultResourceTypes,
setAlignment,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'atlas-map-sheet';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: the page's colours and the maps' tints, one object for both
const palette = {
ink: '#23282b', paper: '#fbfaf6', // a blue-black on a warm white
band: '#1f4a5c', // the accent: opener band, caption bars, table head, references
road: '#b2432f', // the second colour: roads, lights and the place numbers
muted: '#626a6d', rule: '#c8c2b4', // running heads and notes; hairlines
deep: '#8fb9c6', sea: '#cfe3e8', // the maps' water: over and under 20 m
land: '#efe6cf', hill1: '#d9c9a3', hill2: '#bfa97a', forest: '#7f9b6a', // and their land
};
// col(id) links a colour to its palette entry; the drawings read the same hex from `palette`.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.band }) // the defaults' id
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [TEXT, DISPLAY, LABEL] = ['Alegreya Sans', 'Marcellus', 'Alegreya Sans SC'];
const PAGE = { w: 230, h: 300, top: 22, bottom: 22, inner: 18, outer: 16 }; // mm, mirrored
const LEAD = 13.5; // pt: the body's leading and baseline grid
const PT = 25.4 / 72; // mm in a point
// #region answer: a Map type captioned on a bar above the drawing, and where each map goes
// Every caption stands above its drawing or table, in the label face. Maps count 1, 2, 3…
// through the atlas as a type of their own and set their caption on a bar in the band colour.
const captionStyle = { fontFamily: LABEL, fontSize: pt(9), labelColor: col('band'),
position: 'above', gap: mm(1.6), note: { fontSize: pt(7.8), color: col('muted') } };
const MAP_WORD = t({ en: 'Map', es: 'Mapa' });
const mapType = { id: 'map', name: MAP_WORD, shortLabel: MAP_WORD, captionPrefix: MAP_WORD,
numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal',
captionStyle: { backgroundEnabled: true, background: col('band'), color: col('paper'),
labelColor: col('paper'), padding: mm(1.4) } }; // the bar only; the rest is captionStyle's
// Each map floats from its first :ref to the first slot its placement allows.
const PLACEMENT = {
relief: { position: 'bottom', span: 'page' }, // the foot of the page that cites it
north: { position: 'top' }, // the head of the next free column
harbour: { position: 'top' },
chart: { rotate: 'ccw' }, // turned a quarter, top to the left, on a page of its own
The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)
Variations
#Turn the chart the other way
Turned clockwise, the chart has its top and its caption bar at the fore-edge of page 3, and the reader turns the book the opposite way to the usual convention, which 'ccw' follows.
- chart: { rotate: 'ccw' }, // turned a quarter, top to the left, on a page of its own
+ chart: { rotate: 'cw' }, // turned a quarter, top to the right, on a page of its own#Turn a table instead
A table turns with the same setting and, when it is too wide for one page, continues turned on the next under a repeated header row: see the garden almanac.
#Put a map in the margin
In a column-and-a-half layout the outer column can hold figures and their captions and no text: see the textbook with a margin column.
Pitfalls
Pitfall
A 'top' float goes to the page after its citation unless it may head the citing page
By default a float never goes above its own reference, so a page-wide 'top' float cited on page N opens page N+1. Set placement.citingPage: true on the resource or its type's defaultPlacement (or layout.floatsAtCitingPage for the whole book, since postext 1.25) and it heads page N instead, the text above the reference moving down under it, when it fits within layout.maxTopFraction and the citing line stays on that page. It never heads a chapter's first page or a page after a forced break: there it still opens the next page, and 'auto' or 'bottom' can take the foot of the citing page. Figure placement →
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Fonts
- Marcellus (SIL OFL 1.1) · Alegreya Sans (SIL OFL 1.1) · Alegreya Sans SC (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)

