En poques paraules
Tres pàgines d'una guia per començar amb la línia d'ordres de l'ordinador. Ensenya a compondre els exemples de codi en requadres foscos de colors i a dibuixar tecles com Ctrl com a botonets dins del text.
Què compondràs
Tres pàgines del capítol 4 de La terminal, con calma, una guia de butxaca inventada sobre la línia d'ordres, en format de 178 × 229 mm. El text va justificat en Charis SIL, en una columna de 100 mm, amb una columna lateral exterior per a les notes. Cada llistat és un requadre gairebé negre en JetBrains Mono que entra en aquesta columna, sota una pestanya amb el nom del fitxer o de la sessió. Les paraules clau i les ordres que tecleges surten en ambre, les cadenes en verd i els comentaris en gris. Ctrl, Tab i les altres tecles es dibuixen com a tecletes amb contorn dins de les línies justificades, i una xuleta de dreceres amb Ctrl, a dues columnes, ocupa el peu de la pàgina 50. El Markdown conserva els blocs de codi de sempre, i el motor els compon tal com són.
Aquesta recepta respon a
- Com mostro llistats de codi?
- Com faig xips en línia: tecles, etiquetes, bancs de paraules per a exercicis?
- Com escric guions de diàleg, anys a l'inici de paràgraf, preus i símbols literals sense que el Markdown els interpreti malament?
La resposta curta
// 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
};
Ingredients
- Funcions
- Llistats de codiChips en líniaRequadresPestanyes numerades als requadresColumnes en un requadre o al textRequadres a tota l'ampladaRequadres flotantsNotes al margeColumna i mitjaColumna al marge per a flotantsNegreta, cursiva i els seus colorsLlistes numeradesObertures dissenyadesAtributs de títolCapçaleres i folisCapçaleres segons el tipus de pàginaMarges simètricsPaleta de color semànticaEstils de paràgrafTall de línies òptim (Knuth–Plass)
- També fa servir
- Matemàtiques
- Tipografia
- Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
- Recursos
- Cap: totes les imatges es dibuixen en codi
Elaboració
#1 · Dona una caixa a les tanques
El codi d'aquest pas és la resposta curta de més amunt. Cada bloc ``` del Markdown és un bloc de codi: Postext en compon les línies tal com estan escrites, una línia de codi per línia de text, i conserva els sagnats, les línies en blanc del guió i les dues columnes de la sortida de du. codeStyle dissenya tots els llistats alhora (llistats de codi): la lletra i el seu interlineat, l'emplenament gairebé negre, el marge interior i l'espai de damunt i de sota. El que segueix el llenguatge a la línia d'obertura (Terminal, copia.sh) és el títol del llistat, i com que codeStyle.label està fixat, s'imprimeix en una pestanya d'etiqueta sobre la vora superior de la caixa i no en una fila de títol. codeStyle.inline compon el codi en línia del text corrent, ls o grep -c, en la mateixa lletra a 0,88 em (codi en línia). El paràgraf que segueix un llistat va en :::paragraphs{style="resume"}, de manera que comença sense sagnat, com després d'un títol.
#2 · Deixa el text estret i que el codi travessi el marge
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' },
A 10 pt, Charis SIL compon uns 62 caràcters per línia a la columna de 100 mm. La columna lateral d'aquesta disposició a columna i mitja només admet flotants i notes, així que el text no hi entra mai. span: 'page' a codeStyle estén cada llistat per les dues columnes, 143 mm. Dins del seu marge interior, un requadre admet 73 caràcters de JetBrains Mono a 8,6 pt; la línia més llarga d'aquestes pàgines, el comentari que obre copia.sh, en té 68.
#3 · Acoloreix el codi per elements
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,
};
}
El llenguatge de la línia d'obertura (console, bash) tria l'analitzador integrat, i codeStyle.tokens dona a cada tipus d'element el seu color, el seu gruix i la seva inclinació (colors de sintaxi). A copia.sh, les paraules clau com for i done i les ordres internes com set i echo surten en negreta ambre, les cadenes en cursiva verda i els comentaris en gris; els programes, com mkdir o rsync, queden en rodona. L'estil per defecte posa els comentaris en cursiva, així que italic: false els manté drets. En un bloc console, una línia que comença amb un indicador és un element prompt i totes les altres són output, de manera que les ordres que tecleges surten en negreta ambre i la resposta de l'intèrpret es queda en el gris clar del llistat. Els tipus que la recepta no vol acolorir, entre ells els números, les variables i les opcions, prenen també aquest gris.
#4 · Compon les tecles com a xips
// 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) },
];
Les tecles són xips key, amb un emplenament clar i un contorn de 0,6 pt. El seu cos va en punts, de manera que fan 7,8 pt al text de 10 pt, a la nota del marge de 8,6 pt i a la xuleta de 8,4 pt; amb em(0.78), les de la xuleta baixarien a 6,6 pt. Un xip no es parteix mai entre línies ni s'estira (xips en línia), així que en una línia amb tecles tot el buit sobrant va als espais entre paraules. Amb spacing, l'algorisme de partició de línies cerca altres talls abans de deixar que un espai passi del 140 % de la seva amplada normal. Amb el valor per defecte, 200 %, sis línies d'aquestes pàgines el superen; amb l'ajust, la més oberta arriba al 132 %.
#5 · Numera els passos sobre la retícula
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
Els números van en Sora 800 amb el color d'accent, i el separador és un › monoespaiat en gris. Com que la seva lletra i el seu color no són els del número, el separador es dibuixa com un fragment propi (llistes numerades). Els marges de la llista són zero, així que els passos continuen a la retícula de base de 14,5 pt del text que els envolta. Els 1,5 em per defecte obririen 5,3 mm sobre els passos i durien la xuleta a la pàgina 51.
#6 · Porta la xuleta al peu de la pàgina
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 } };
La xuleta és un estil de requadre amb l'emplenament dels llistats, Sora per a les accions i placement: 'bottom', que la fa flotar fins al peu de la pàgina 50 (requadres flotants). Dins del flux, un requadre que travessa la pàgina necessita lloc per a si mateix i per a dues línies de text a sota. Aquí saltaria a la pàgina 51 amb 58 mm buits sota els passos, i el capítol passaria a quatre pàgines. Al Markdown, :::columns{count=2 breaks="8"} obre la columna dreta al vuitè bloc, el seu títol. L'equilibratge tot sol talla per alçada, i quan una acció ocupa dues línies deixa Órdenes e historial al peu de la columna esquerra. Cada entrada comença pels mateixos dos xips, Ctrl i una lletra, tots dos en la monoespaiada, així que les accions arrenquen a la mateixa distància de la vora esquerra de la seva columna.
La recepta completa
// ═══ 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 = 'es'; // @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 },
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
#Penja la pestanya a la dreta
La pestanya passa a la cantonada superior dreta del requadre, que en una pàgina senar queda sobre la columna lateral.
- position: 'top-left' },
+ position: 'top-right' },#Numera les línies
Cada llistat porta números de línia en gris en un marge dins de la caixa. Aquest marge ocupa uns quatre dels 73 caràcters, i en queden 69: el comentari que obre copia.sh, de 68, encara hi cap, però un sol caràcter més el faria partir, i la resta continuaria a sota darrere d'un ». La revisió del Receptari ho indica amb un avís codeOverflow; escurça la línia per mantenir el guió en les seves 13 línies. Un sol llistat rep números amb {lineNumbers} a la línia d'obertura.
+ lineNumbers: true, lineNumberColor: col('slate'),
tokens: tokens(), // the colours, below#Dona als comentaris el color de les cadenes
Els comentaris prenen el verd de les cadenes, en cursiva.
- comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+ comment: { color: col('phosphor'), italic: true }, // the strings' green italicErrors freqüents
Error freqüent
Un requadre lateral comença a l'altura del bloc que segueix la seva tanca
A postext 1.4.1, un requadre amb span: 'side' es col·loca a la columna lateral a l'altura on ha arribat el text a la seva tanca, a la línia següent de la retícula i sota els requadres que ja hi hagi. Posa la tanca d'una glossa just abans del paràgraf que explica: si va després, la glossa comença al costat del paràgraf següent. Un requadre que passaria del peu de la columna puja fins que el seu peu coincideix amb el de la columna, si el requadre de sobre li deixa lloc; si tot i així no hi cap, espera la columna lateral de la pàgina següent. Notes al marge →
- No passis de 73 caràcters en cap línia de codi. Una línia més llarga es parteix després de l'últim espai o signe de puntuació que hi cap i continua a sota darrere d'un
», i el motor genera un avíscodeOverflow;overflow: 'shrink'compon tot el llistat més petit, i'clip'talla la línia a la vora de la caixa. - Un tabulador d'un llistat avança fins al múltiple següent de quatre columnes (
codeStyle.tabSize). Un guió sagnat amb tabuladors que el teu editor mostra amb vuit columnes d'amplada aquí surt més estret. - Amb
codeStyle.inlinefixat, el codi en línia no es parteix mai entre línies, igual que un xip. Una ruta llarga dins del text, com~/Imatges/2025/IMG_0977.MOV, passa sencera a la línia següent i pot deixar enrere una línia massa oberta.
Crèdits
- Recepta
- Ignacio Ferro
- Text
- Text original, CC BY 4.0
- Fonts
- Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (SIL OFL 1.1)
- Codi
- MIT, com Postext
Editar aquest text ↗ (s'obre en una pestanya nova)Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)


