In short
Three pages of a beginner's guide to the computer command line. It shows how to set code examples in dark coloured boxes and draw keys like Ctrl as small buttons in the text.
What you'll build
Three pages from chapter 4 of The Shell, Gently, an invented pocket guide to the command line, on a 178 × 229 mm page. The text is justified Charis SIL in a 100 mm column, with a margin column on the outer side for notes. Each listing is a near-black box of JetBrains Mono that runs into that column, under a tab with the name of the file or the session. Keywords and typed commands print in amber, strings in green and comments in grey. Keys such as Ctrl and Tab are small outlined keycaps inside the justified lines, and a two-column cheat sheet of Ctrl shortcuts fills the foot of page 50. The Markdown keeps ordinary fenced code blocks, and the engine sets them as they are.
This recipe answers
- How do I show code listings?
- How do I make inline chips: keyboard keys, tags, word banks for exercises?
- How do I write dialogue dashes, years at a paragraph start, prices and literal symbols without Markdown misreading them?
The short answer
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
background: col('night'), span: 'page', // across the text and the margin
padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
marginTop: mm(6), marginBottom: mm(2.5),
label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
position: 'top-left' },
tokens: tokens(), // the colours, below
inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};
A fence is a code listing; codeStyle gives it a dark box
Ingredients
- Features
- Code listingsInline chipsCallout boxesNumbered box tabsColumns in a box or in the textBoxes across the pageFloated boxesMargin notesColumn and a halfMargin column for floatsBold, italic and their coloursNumbered listsDesigned openersHeading attributesRunning heads and foliosHeads by page roleMirrored marginsSemantic colour paletteParagraph stylesOptimal line breaking (Knuth–Plass)
- Also uses
- Mathematics
- Type
- Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · Give the fences a box
The code for this step is the short answer above. Each ``` fence in the Markdown is a code block: Postext sets its lines as typed, one line of code to a line of type, with the indents, the blank lines of the script and the two-column output of du kept. codeStyle designs every listing at once (code listings): the face and its leading, the near-black fill, the padding and the room above and below. Whatever follows the language on the fence line (Terminal, backup.sh) is the listing's title, and because codeStyle.label is set it prints on a label tab on the box's top edge rather than in a title row. codeStyle.inline sets the inline code of the running text, ls or grep -c, in the same face at 0.88 em (inline code). The paragraph after a listing goes in :::paragraphs{style="resume"}, so it starts flush, as it would after a heading.
#2 · Keep the text narrow and let the code cross the margin
page: { sizePreset: 'custom', width: mm(178), height: mm(229), margins: {
top: mm(22), bottom: mm(21), left: mm(20), right: mm(OUTER), mirror: true } },
layout: { layoutType: 'oneAndHalf', sideColumnPercent: 26, gutterWidth: mm(6),
sideColumnRole: 'floats', sideColumnSide: 'outer' },
At 10 pt, Charis SIL sets about 62 characters in the 100 mm column. The side column of this column-and-a-half layout takes only floats and notes, so the text never runs into it. span: 'page' in codeStyle stretches every listing across both columns, 143 mm. Inside its padding a box holds 73 characters of JetBrains Mono at 8.6 pt; the longest line on these pages, the comment that opens backup.sh, has 71.
#3 · Colour the code by token
function tokens() {
const plain = { color: col('code') }; // every other kind in the listing's own colour
return {
keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },
string: { color: col('phosphor'), italic: true },
comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
prompt: { color: col('amber'), bold: true }, output: plain, // what you type, the answer
number: plain, type: plain, variable: plain, meta: plain, operator: plain, punctuation: plain,
};
}
The language on the fence (console, bash) picks the built-in tokenizer, and codeStyle.tokens gives each kind of token its colour, weight and slant (syntax colouring). In backup.sh, keywords such as for and done and builtins such as set and echo print in amber bold, strings in green italic and comments in grey; programs like mkdir and rsync stay plain. The default style sets comments in italics, so italic: false keeps them upright. In a console fence a line that opens with a prompt is a prompt token and every other line is output, so the commands you type print in amber bold and the shell's answer stays in the listing's light grey. The kinds the recipe does not want coloured, numbers, variables and options among them, take that grey too.
#4 · Set keys as chips
// Chips never break or stretch, so a line with keys puts all its slack in its word spaces;
// the breaker tries other breaks before a space passes 140 % (default 200 %).
const spacing = { maxWordSpacing: 1.4 }; // spread into bodyText
const chipStyles = [
{ id: 'key', fontFamily: MONO, fontSize: pt(7.8), bold: true, color: col('ink'),
background: col('code'), borderColor: col('slate'), borderWidth: pt(0.6),
borderRadius: pt(1.6), paddingX: em(0.45), paddingY: em(0.14), gap: em(0.3) },
];
Keys are key chips with a light fill and a 0.6 pt outline. Their size is given in points, so a key measures 7.8 pt in the 10 pt text, in the 8.6 pt margin note and in the 8.4 pt cheat sheet; em(0.78) would shrink the cheat sheet's keys to 6.6 pt. A chip never breaks across lines and never stretches (inline chips), so a line with keys puts all its slack in its word spaces. spacing makes the line breaker try other breaks before a space grows past 140 % of its normal width. At the default, 200 %, six lines of these pages stretch further than that; with the setting, the widest reaches 132 %.
#5 · Number the steps on the grid
const orderedLists = { fontFamily: DISPLAY, fontWeight: 800, color: col('ember'),
gap: em(0.7), separator: '›', separatorGap: em(0.25), separatorFontFamily: MONO,
separatorFontWeight: 700, separatorColor: col('muted'),
marginTop: ZERO, marginBottom: ZERO }; // the default 1.5 em opens 5.3 mm above and below
The numbers are Sora 800 in the accent, and the separator is a mono › in grey. The separator has its own face and colour, so it is drawn as a separate run (ordered lists). The list margins are zero, so the steps continue on the 14.5 pt grid of the text around them. The default 1.5 em would open 5.3 mm above the steps and push the cheat sheet to page 51.
#6 · Float the cheat sheet to the foot of the page
const sheet = { id: 'sheet', background: col('night'), span: 'page', placement: 'bottom',
marginTop: mm(6), marginBottom: mm(2.5),
columnGap: mm(8), padding: { top: mm(5), right: mm(6), bottom: mm(5.5), left: mm(6) },
titleStyle: { fontFamily: MONO, fontSize: pt(7.5), fontWeight: 700, gap: mm(3.5),
color: col('phosphor'), textTransform: 'uppercase', letterSpacing: pt(1.5) },
body: { fontFamily: DISPLAY, fontSize: pt(8.4), lineHeight: pt(13), textAlign: 'left',
color: col('code'), boldColor: col('amber'), italicColor: col('phosphor'),
paragraphSpacing: false, firstLineIndent: ZERO } };
The cheat sheet is a callout style with the listings' fill, Sora for the actions, and placement: 'bottom', which floats it to the foot of page 50 (floated boxes). Left in the flow, a box across the page needs room for itself and two lines of text under it. Here the box would move to page 51, leaving 58 mm empty under the steps, and the chapter would run to four pages. In the Markdown, :::columns{count=2 breaks="8"} opens the right column at the eighth block, its heading. Balancing alone cuts by height, and when one action runs to a second line it leaves Commands and history at the foot of the left column. Every entry opens with the same two chips, Ctrl and a letter, both in the mono face, so each action begins at the same distance from the left edge of its column.
The whole recipe
// ═══ Postext Cookbook · Nº 048 · Code listings and keycaps ═══
// https://postext.dev/en/cookbook/code-listings-and-keycaps
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, prepareFonts, withLoadedFonts, renderPageToCanvas,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'code-listings-and-keycaps';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1b1f24', muted: '#5c636b', ember: '#9a5410', // text, heads, accent
night: '#0e1116', code: '#d3d9df', amber: '#f2b134', phosphor: '#3ddc84', // the listings
slate: '#8a939d' }; // comments in a listing, the outline of a key (code is its face)
// Every colour is linked to its palette entry by id.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.ember })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Charis SIL', 'Sora', 'JetBrains Mono'];
const LEAD = 14.5; // pt: the body leading, the page's baseline grid
const ZERO = pt(0);
// #region answer: a fence is a code listing; codeStyle gives it a dark box
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
background: col('night'), span: 'page', // across the text and the margin
padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
marginTop: mm(6), marginBottom: mm(2.5),
label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
position: 'top-left' },
tokens: tokens(), // the colours, below
inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};
// #endregion
// #region paint: keywords amber, strings green, comments slate; a session's typed lines amber
function tokens() {
const plain = { color: col('code') }; // every other kind in the listing's own colour
return {
keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },
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
#Hang the tab on the right
The tab moves to the box's top-right corner, which on a recto stands over the margin column.
- position: 'top-left' },
+ position: 'top-right' },#Number the lines
Every listing gets line numbers in grey in a gutter inside its box. The gutter takes about four characters of the 73, so the comment that opens backup.sh no longer fits: it turns over after backup, and disk. goes on below behind a ». The Cookbook's check reports it as a codeOverflow warning; shorten the comment to keep the script on its 13 lines. A single listing takes numbers with {lineNumbers} on its fence line.
+ lineNumbers: true, lineNumberColor: col('slate'),
tokens: tokens(), // the colours, below#Give comments the colour of strings
The comments take the green of the strings, in italics.
- comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+ comment: { color: col('phosphor'), italic: true }, // the strings' green italicPitfalls
Pitfall
A side box starts level with the block after its fence
In postext 1.4.1 a span: 'side' box stands in the side column at the height the text has reached at its fence, on the next grid line, and under any box already there. Fence a gloss just before the paragraph it explains: fenced after it, the gloss starts beside the next paragraph. A box that would run past the column's foot slides up until its foot sits on the column's foot, as far as the box above it allows; one that still does not fit waits for the side column of the next page. Margin notes →
- Keep every code line within 73 characters. A longer one turns over at its last space or punctuation that fits and goes on below behind a
», and the engine reports acodeOverflowwarning;overflow: 'shrink'sets the whole listing smaller instead, and'clip'cuts the line at the box's edge. - A tab in a listing advances to the next multiple of four columns (
codeStyle.tabSize). A script indented with tabs that your editor shows eight columns wide comes out narrower here. - With
codeStyle.inlineset, inline code never breaks across lines, as a chip does. A long path in running text, such as~/Pictures/2025/IMG_0977.MOV, moves whole to the next line and can leave a loose one behind it.
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Fonts
- Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


