Em poucas palavras
Três páginas de um guia para iniciantes na linha de comando do computador. Mostra como compor exemplos de código em caixas escuras coloridas e desenhar teclas como Ctrl como botõezinhos no texto.
O que você vai compor
Três páginas do capítulo 4 de The Shell, Gently, um guia de bolso inventado sobre a linha de comando, numa página de 178 × 229 mm. O texto vai justificado em Charis SIL, numa coluna de 100 mm, com uma coluna lateral do lado externo para as notas. Cada listagem é um boxe quase preto em JetBrains Mono que entra nessa coluna, sob uma aba com o nome do arquivo ou da sessão. Palavras-chave e comandos digitados saem em âmbar, strings em verde e comentários em cinza. Teclas como Ctrl e Tab são pequenas teclas contornadas dentro das linhas justificadas, e uma colinha de atalhos com Ctrl, em duas colunas, ocupa o pé da página 50. O Markdown mantém os blocos de código delimitados de sempre, e o motor os compõe como estão.
Esta receita responde a
- Como mostro listagens de código?
- Como faço chips em linha: teclas, etiquetas, bancos de palavras para exercícios?
- Como escrevo travessões de diálogo, anos no início do parágrafo, preços e símbolos literais sem que o Markdown os interprete errado?
A 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
};
Ingredientes
- Funcionalidades
- Listagens de códigoChips no textoBoxesAbas numeradas nos boxesColunas num boxe ou no textoBoxes na largura da páginaBoxes flutuantesNotas na margemColuna e meiaColuna de margem para flutuantesNegrito, itálico e suas coresListas numeradasAberturas desenhadasAtributos de títuloCabeços e fóliosCabeços por tipo de páginaMargens espelhadasPaleta de cores semânticaEstilos de parágrafoQuebra de linha ótima (Knuth–Plass)
- Também usa
- Matemática
- Tipografia
- Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
- Materiais
- Nenhum: todas as imagens são desenhadas em código
Preparo
#1 · Dar um boxe às cercas
O código deste passo é a resposta curta lá em cima. Cada bloco delimitado por ``` no Markdown é um bloco de código: o Postext compõe as linhas como foram digitadas, uma linha de código por linha composta, mantendo os recuos, as linhas em branco do script e as duas colunas da saída de du. codeStyle desenha todas as listagens de uma vez (listagens de código): a fonte e a entrelinha, o preenchimento quase preto, o espaçamento interno e o espaço acima e abaixo. O que vem depois da linguagem na linha de abertura (Terminal, backup.sh) é o título da listagem, e como codeStyle.label está definido ele é impresso numa aba de rótulo na borda superior do boxe, e não numa linha de título. codeStyle.inline compõe o código em linha do texto corrido, ls ou grep -c, na mesma fonte a 0,88 em (código em linha). O parágrafo depois de uma listagem vai em :::paragraphs{style="resume"}, por isso começa sem recuo, como depois de um título.
#2 · Manter o texto estreito e deixar o código atravessar a margem
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, a Charis SIL compõe cerca de 62 caracteres na coluna de 100 mm. A coluna lateral deste layout de coluna e meia só recebe flutuantes e notas, de modo que o texto nunca entra nela. O span: 'page' de codeStyle estende cada listagem pelas duas colunas, 143 mm. Dentro do espaçamento interno, um boxe comporta 73 caracteres de JetBrains Mono a 8,6 pt; a linha mais longa destas páginas, o comentário que abre backup.sh, tem 71.
#3 · Colorir o código por elemento
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,
};
}
A linguagem do bloco (console, bash) escolhe o tokenizador integrado, e codeStyle.tokens dá a cada tipo de elemento a cor, o peso e a inclinação (coloração de sintaxe). Em backup.sh, palavras-chave como for e done e comandos internos como set e echo saem em negrito âmbar, as strings em itálico verde e os comentários em cinza; programas como mkdir e rsync ficam sem destaque. O estilo padrão põe os comentários em itálico, por isso italic: false os mantém em redondo. Num bloco console, uma linha que abre com um prompt é um elemento prompt e todas as outras são output, por isso os comandos que você digita saem em negrito âmbar e a resposta do shell fica no cinza-claro da listagem. Os tipos que a receita não quer colorir, entre eles números, variáveis e opções, também recebem esse cinza.
#4 · Compor as teclas como 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) },
];
As teclas são chips key, com um preenchimento claro e um contorno de 0,6 pt. O tamanho delas é dado em pontos, de modo que uma tecla mede 7,8 pt no texto de 10 pt, na nota de margem de 8,6 pt e na colinha de 8,4 pt; em(0.78) encolheria as teclas da colinha para 6,6 pt. Um chip nunca se divide entre linhas nem se estica (chips em linha), por isso uma linha com teclas joga toda a folga nos espaços entre palavras. spacing faz o algoritmo de quebra de linhas tentar outras quebras antes de deixar um espaço passar de 140 % da largura normal. No padrão, 200 %, seis linhas destas páginas se esticam além disso; com o ajuste, a mais aberta chega a 132 %.
#5 · Numerar os passos na grade
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
Os números são Sora 800 na cor de destaque, e o separador é um › monoespaçado em cinza. O separador tem fonte e cor próprias, por isso é desenhado como um trecho separado (listas numeradas). As margens da lista são zero, de modo que os passos continuam na grade de 14,5 pt do texto ao redor. O 1,5 em padrão abriria 5,3 mm acima dos passos e empurraria a colinha para a página 51.
#6 · Levar a colinha flutuando até o pé da 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 } };
A colinha é um estilo de boxe com o preenchimento das listagens, Sora para as ações e placement: 'bottom', que a faz flutuar até o pé da página 50 (boxes flutuantes). Deixado no fluxo, um boxe na largura da página precisa de espaço para si e para duas linhas de texto embaixo. Aqui o boxe passaria para a página 51, deixando 58 mm vazios sob os passos, e o capítulo iria para quatro páginas. No Markdown, :::columns{count=2 breaks="8"} abre a coluna da direita no oitavo bloco, o título. O equilíbrio sozinho corta pela altura, e quando uma ação ocupa uma segunda linha ele deixa Commands and history no pé da coluna da esquerda. Toda entrada começa com os mesmos dois chips, Ctrl e uma letra, ambos na monoespaçada, por isso cada ação começa à mesma distância da borda esquerda da coluna.
A receita 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 = '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 },
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
#Pendurar a aba à direita
A aba passa para o canto superior direito do boxe, que num recto fica sobre a coluna lateral.
- position: 'top-left' },
+ position: 'top-right' },#Numerar as linhas
Cada listagem ganha números de linha em cinza numa margem dentro do boxe. A margem ocupa uns quatro dos 73 caracteres, por isso o comentário que abre backup.sh deixa de caber: ele quebra depois de backup, e disk. continua abaixo, atrás de um ». A verificação das Receitas o aponta como um aviso codeOverflow; encurte o comentário para manter o script nas 13 linhas. Uma só listagem recebe números com {lineNumbers} na linha de abertura do bloco.
+ lineNumbers: true, lineNumberColor: col('slate'),
tokens: tokens(), // the colours, below#Dar aos comentários a cor das strings
Os comentários recebem o verde das strings, em itálico.
- comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+ comment: { color: col('phosphor'), italic: true }, // the strings' green italicErros comuns
Erro comum
Um boxe lateral começa na altura do bloco que vem depois do seu delimitador
No postext 1.4.1, um boxe com span: 'side' fica na coluna lateral na altura a que o texto chegou no seu delimitador, na linha seguinte da grade e abaixo dos boxes que já estiverem ali. Abra o delimitador de uma glosa logo antes do parágrafo que ela explica: se vier depois, a glosa começa ao lado do parágrafo seguinte. Um boxe que passaria do pé da coluna sobe até seu pé coincidir com o da coluna, se o boxe de cima permitir; se mesmo assim não couber, espera pela coluna lateral da página seguinte. Notas na margem →
- Mantenha toda linha de código em até 73 caracteres. Uma linha mais longa quebra no último espaço ou sinal de pontuação que cabe e continua abaixo, atrás de um
», e o motor gera um avisocodeOverflow;overflow: 'shrink'compõe a listagem inteira menor, e'clip'corta a linha na borda do boxe. - Uma tabulação numa listagem avança até o múltiplo seguinte de quatro colunas (
codeStyle.tabSize). Um script recuado com tabulações que seu editor mostra com oito colunas de largura sai mais estreito aqui. - Com
codeStyle.inlinedefinido, o código em linha nunca se divide entre linhas, como um chip. Um caminho longo no texto corrido, como~/Pictures/2025/IMG_0977.MOV, passa inteiro para a linha seguinte e pode deixar para trás uma linha frouxa.
Créditos
- Receita
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Fontes
- Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (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)


