Saltar al contenido principal
Receta número 48

Recetario · Capítulo 6 · Recuadros y notas

Listados de código y teclas

Guía de la terminal cuyos bloques de código se componen como recuadros oscuros, coloreados por elementos, con las teclas como chips.

pp. 50–51 · 2–3 de 3

  • Formato 178 × 229 mm
  • Columna y media, medianil de 6 mm
  • Charis SIL 10/14,5
  • JetBrains Mono
  • Sora
  • 3 páginas
  • Nivel
  • Postext 1.57.1
  • Compuesto en 89 ms
  • 147 líneas de código

En pocas palabras

Tres páginas de una guía para empezar con la línea de comandos del ordenador. Enseña a componer los ejemplos de código en recuadros oscuros de colores y a dibujar teclas como Ctrl como botoncitos en el texto.

Lo que vas a componer

Tres páginas del capítulo 4 de La terminal, con calma, una guía de bolsillo inventada sobre la línea de comandos, en formato de 178 × 229 mm. El texto va justificado en Charis SIL, en una columna de 100 mm, con una columna lateral exterior para las notas. Cada listado es un recuadro casi negro en JetBrains Mono que entra en esa columna, bajo una pestaña con el nombre del archivo o de la sesión. Las palabras clave y las órdenes que tecleas salen en ámbar, las cadenas en verde y los comentarios en gris. Ctrl, Tab y las demás teclas se dibujan dentro de las líneas justificadas, y una chuleta de atajos con Ctrl, a dos columnas, ocupa el pie de la página 50. El Markdown conserva los bloques de código de siempre, y el motor los compone tal como están.

Esta receta responde a

  • ¿Cómo muestro listados de código?
  • ¿Cómo hago chips en línea: teclas, etiquetas, bancos de palabras para ejercicios?
  • ¿Cómo escribo rayas de diálogo, años al principio de párrafo, precios y símbolos literales sin que el Markdown los malinterprete?

La respuesta corta

script.js · líneas 26–41en el código completo
// 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
};

Ingredientes

También usa
Matemáticas
Tipografía
Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
Recursos
Ninguno: todas las imágenes se dibujan en código

Elaboración

#1 · Da a los bloques de código un recuadro

El código de este paso es la respuesta corta de arriba. Cada bloque ``` del Markdown es un bloque de código: Postext compone sus líneas tal como están escritas, una línea de código por línea impresa, y conserva las sangrías, las líneas en blanco del guion y las dos columnas de la salida de du. codeStyle diseña todos los listados a la vez (listados de código): la letra y su interlineado, el fondo casi negro, el margen interior y el espacio por encima y por debajo. Lo que sigue al lenguaje en la línea de apertura (Terminal, copia.sh) es el título del listado, y como codeStyle.label está fijado, se imprime en una pestaña sobre el borde superior del recuadro y no en una fila de título. codeStyle.inline compone el código en línea del texto, ls o grep -c, en la misma letra a 0,88 em (código en línea). El párrafo que sigue a un listado va en :::paragraphs{style="resume"}, así que empieza sin sangría, como tras un título.

#2 · Deja el texto estrecho y que el código cruce el margen

script.js · líneas 124–127en el código completo
  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 compone unos 62 caracteres por línea en la columna de 100 mm. La columna lateral de esta disposición a columna y media solo admite flotantes y notas, así que el texto nunca entra en ella. El span: 'page' de codeStyle extiende cada listado por las dos columnas, 143 mm. Dentro de su margen interior, un recuadro admite 73 caracteres de JetBrains Mono a 8,6 pt; la línea más larga de estas páginas, el comentario que abre copia.sh, tiene 68.

#3 · Colorea el código por elementos

script.js · líneas 45–54en el código completo
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 lenguaje de la línea de apertura (console, bash) elige el analizador integrado, y codeStyle.tokens da a cada clase de elemento su color, su peso y su inclinación (coloreado de sintaxis). En copia.sh, las palabras clave, como for y done, y las órdenes internas, como set y echo, salen en negrita ámbar, las cadenas en cursiva verde y los comentarios en gris; los programas, como mkdir o rsync, quedan en redonda. El estilo por defecto pone los comentarios en cursiva, así que italic: false los pone en redonda. En un bloque console, una línea que empieza por un indicador es un elemento prompt y cualquier otra es output, de modo que las órdenes que tecleas salen en negrita ámbar y la respuesta del intérprete se queda en el gris claro del listado. Las clases que la receta no quiere colorear, entre ellas los números, las variables y las opciones, toman también ese gris.

#4 · Compón las teclas como chips

script.js · líneas 58–65en el código completo
// 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) },
];

Las teclas son chips key, con un relleno claro y un contorno de 0,6 pt. Su cuerpo va en puntos, así que miden 7,8 pt en el texto de 10 pt, en la nota del margen de 8,6 pt y en la chuleta de 8,4 pt; con em(0.78), las de la chuleta bajarían a 6,6 pt. Un chip nunca se parte entre líneas ni se estira (chips en línea), así que en una línea con teclas todo el hueco sobrante va a los espacios entre palabras. Con spacing, el algoritmo de partición de líneas busca otros cortes antes de dejar que un espacio pase del 140 % de su anchura normal. Con el valor por defecto, 200 %, cinco líneas de estas páginas lo superan; con el ajuste, la más abierta llega al 138 %.

#5 · Numera los pasos sobre la rejilla

script.js · líneas 91–94en el código completo
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

Los números van en Sora 800 con el color de acento, y el separador es un › monoespaciado en gris. Como su letra y su color no son los del número, el separador se dibuja como un fragmento propio (listas ordenadas). Los márgenes de la lista son cero, así que los pasos siguen en la rejilla base de 14,5 pt del texto que los rodea. Los 1,5 em por defecto abrirían 5,3 mm sobre los pasos y llevarían la chuleta a la página 51.

#6 · Lleva la chuleta al pie de la página

script.js · líneas 69–76en el código completo
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 chuleta es un estilo de recuadro con el fondo de los listados, Sora para las acciones y placement: 'bottom', que la hace flotar hasta el pie de la página 50 (recuadros flotantes). Dentro del flujo, un recuadro que cruza la página necesita sitio para sí y para dos líneas de texto debajo. Aquí saltaría a la página 51 con 58 mm vacíos bajo los pasos, y el capítulo se iría a cuatro páginas. En el Markdown, :::columns{count=2 breaks="8"} abre la columna derecha en el octavo bloque, su título. El equilibrado por sí solo corta por altura, y cuando una acción ocupa dos líneas deja Órdenes e historial al pie de la columna izquierda. Cada entrada empieza por los mismos dos chips, Ctrl y una letra, los dos en la monoespaciada, así que las acciones arrancan a la misma distancia del borde izquierdo de su columna.

La receta completa

Sandbox
// ═══ 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 },

El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)

Variantes

#Cuelga la pestaña a la derecha

La pestaña pasa a la esquina superior derecha del recuadro, que en una página impar queda sobre la columna lateral.

-    position: 'top-left' },
+    position: 'top-right' },

#Numera las líneas

Cada listado lleva los números de línea en gris, en un margen dentro de su recuadro. Ese margen ocupa unos cuatro de los 73 caracteres, y el comentario que abre copia.sh, con 68, todavía cabe: el guion conserva sus 13 líneas y no hay aviso codeOverflow. Un comentario de más de 69 caracteres se partiría y seguiría debajo tras una ». Un listado suelto se numera con {lineNumbers} en su línea de apertura.

+  lineNumbers: true, lineNumberColor: col('slate'),
   tokens: tokens(), // the colours, below

#Da a los comentarios el color de las cadenas

Los comentarios toman el verde de las cadenas, en cursiva.

-    comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+    comment: { color: col('phosphor'), italic: true }, // the strings' green italic

Errores frecuentes

Error frecuente

Un recuadro lateral empieza a la altura del bloque que sigue a su valla

En postext 1.4.1, un recuadro con span: 'side' se coloca en la columna lateral a la altura a la que ha llegado el texto en su valla, en la siguiente línea de la rejilla y debajo de los recuadros que ya haya. Pon la valla de una glosa justo antes del párrafo que explica: si va después, la glosa empieza junto al párrafo siguiente. Un recuadro que pasaría del pie de la columna sube hasta que su pie coincide con el de la columna, si el recuadro de encima le deja sitio; si aun así no cabe, espera a la columna lateral de la página siguiente. Notas al margen →

  • No pases de 73 caracteres en ninguna línea de código. Una línea más larga se parte tras el último espacio o signo de puntuación que cabe y sigue debajo tras una », y el motor da un aviso codeOverflow; con overflow: 'shrink', todo el listado se compone más pequeño, y con 'clip', la línea se corta en el borde del recuadro.
  • Un tabulador en un listado avanza hasta el siguiente múltiplo de cuatro columnas (codeStyle.tabSize). Un guion sangrado con tabuladores que tu editor muestra a ocho columnas sale aquí más estrecho.
  • Con codeStyle.inline fijado, el código en línea nunca se parte entre líneas, igual que un chip. Una ruta larga en el texto, como ~/fotos/2025/IMG_0977.MOV, pasa entera a la línea siguiente y puede dejar detrás una línea muy abierta.

Créditos

Texto
Texto original, CC BY 4.0
Fuentes
Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (SIL OFL 1.1)
Sandbox