Capítulo 5 · Parte II · O ofício
Formato do documento
O subconjunto de Markdown que o Postext lê: o front matter, os títulos, as listas e os blocos de código; o que ele ignora; e as regras para escrever os documentos de origem
Em poucas palavras
Esta página explica como escrever um texto que o Postext consiga diagramar. Você escreve em Markdown, um jeito simples de escrever em que alguns símbolos marcam títulos, listas, palavras em negrito e links. Esta página trata das linhas do início do arquivo, dos títulos, das listas, do código e das marcas que o Postext ignora. Outras quatro páginas tratam dos blocos, como boxes e colunas, das marcas dentro da linha, das notas e referências, e das imagens e tabelas. No final, traz conselhos para escrever um texto fácil de ler.
O Postext lê um dialeto de Markdown pequeno de propósito.
O analisador é um tokenizador escrito à mão, e não uma implementação completa do CommonMark; por isso, o formato de origem é restrito e previsível. A intenção é dupla: manter o motor pequeno e rápido, e tornar os documentos fáceis de levar entre o Postext e qualquer outro leitor de CommonMark (Obsidian, Pandoc, VS Code…). Tudo o que não estiver listado nesta página é tratado como texto simples ou removido do fluxo em linha.
Se você monta um documento por programação, a função parseMarkdown (veja Configuração › Análise do Markdown) devolve exatamente a estrutura de blocos que o motor de layout consome.
#Front matter
Um documento pode começar com um bloco opcional de front matter em YAML, delimitado por marcadores ---:
---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---
# Chapter One
The story begins here…Chame extractFrontmatter(source) para separar o front matter do corpo. O objeto de metadados lido é devolvido junto com o Markdown restante e com a posição, em caracteres, em que o corpo começa; isso é útil se você precisa relacionar erros ou posições do cursor com o texto original.
O front matter é lido com o gray-matter; por isso, qualquer forma de YAML é aceita. O próprio Postext só usa title, subtitle, author e publishDate; as outras chaves ficam guardadas em PostextContent.metadata e são suas para usar como quiser.
Um bloco que não é YAML válido — aspas sem fechar, texto depois de um valor entre aspas — não interrompe a diagramação: extractFrontmatter não devolve metadados, toma como corpo o texto depois do --- de fechamento e deixa o motivo do analisador em error. O documento é diagramado sem os metadados, e a compilação acrescenta uma entrada invalidFrontmatter a contentWarnings (o Sandbox a mostra como Front matter inválido).
O YAML atribui um tipo a cada valor: 1984 é um número, 2026-04-15 uma data, [Ana Gil, Luis Paz] uma lista. O Postext imprime cada um desses quatro campos como texto, qualquer que seja o tipo:
- um número na forma decimal simples, e um booleano como
trueoufalse(title: 1984imprime 1984). O YAML lê um número como valor, não dígito por dígito:1.50imprime 1.5,017(octal) 15,1:30(base 60) 90; - uma data como o dia do calendário, escrito por extenso no idioma do documento (a configuração
localeou, na falta dela, o idioma da hifenização):publishDate: 2026-04-15imprime April 15, 2026 em inglês, 15 de abril de 2026 em espanhol, 15. April 2026 em alemão. As datas em árabe usam o calendário gregoriano, a menos que a etiqueta indique outro (ar-u-ca-islamicimprime a data da Hégira), com os algarismos que a etiqueta implica (ar-EG: ١٥ أبريل ٢٠٢٦;ar-u-nu-latn: 15 أبريل 2026). Uma data com hora imprime o dia correspondente em UTC e descarta a hora:2026-09-24T23:30:00-05:00são 04:30 UTC do dia 25 e imprime September 25, 2026; - uma lista como os itens unidos por vírgulas (
author: [Ana Gil, Luis Paz]imprime Ana Gil, Luis Paz).
Coloque um valor entre aspas para imprimi-lo exatamente como está escrito, seja um número que precisa manter os dígitos, seja uma data que precisa manter o dia: publishDate: "15/04/2026", title: "1984". O texto chega a doc.metadata, aos marcadores ({title}, {publishDate}…) e ao título e autor do PDF. Se um dos quatro campos não tiver forma de texto (um mapa aninhado, um title: vazio), ele fica fora de doc.metadata. extractFrontmatter continua devolvendo os valores com os tipos que o YAML deu; metadataText(value, locale) devolve o texto que o Postext imprime para um deles.
#Elementos de bloco
O Postext reconhece sete tipos de bloco de texto e as listagens de código, além das diretivas e das inserções de recursos, descritas em páginas próprias. Um bloco sempre termina com uma linha em branco ou com o início de outro bloco.
| Construção | Sintaxe | Observações |
|---|---|---|
| Título | # Title … ###### H6 | De um a seis caracteres #, seguidos de um espaço e do texto do título. Os níveis 1–6 correspondem diretamente à configuração headings.levels. |
| Parágrafo | Texto simples em uma ou mais linhas | Linhas consecutivas que não estão em branco nem são especiais são unidas com um único espaço e saem como um só parágrafo. Entre dois caracteres chineses ou japoneses (ideogramas, kana, pontuação de largura total, e aspas curvas, travessões ou reticências ao lado deles), a quebra de linha é descartada, como faz o CSS; por isso, um parágrafo em chinês pode ser quebrado em qualquer ponto do texto de origem. Entre duas dessas marcas (“你好”⏎“再见”, 他说……⏎“好”), decidem os caracteres que vêm depois delas: a quebra de linha some quando um deles é chinês ou japonês, e “hello”⏎“bye” mantém o espaço. O coreano mantém o espaço. Uma quebra de linha digitada no texto não se mantém, a não ser que a linha termine em uma barra invertida (uma quebra de linha forçada, veja Quebras de linha); uma linha em branco começa um parágrafo novo. Uma tabulação digitada no texto também é um espaço entre palavras, a não ser que o estilo do parágrafo defina paradas de tabulação; :tab é sempre uma tabulação (veja Tabulações e paradas de tabulação). Um poema, cujas linhas devem ficar como foram escritas, vai em um bloco :::verse. |
| Citação | > quoted text | Cada linha da citação precisa começar com > (com um espaço opcional depois). Linhas de citação consecutivas se juntam em um único bloco de citação, unidas como as linhas de um parágrafo. A citação é composta conforme bodyText.blockquote: itálico cinza com o recuo de primeira linha do corpo, a menos que você mude isso (veja Configuração › Citações). |
| Lista não ordenada | - item, * item, + item | Qualquer um dos três marcadores é aceito. Um item fica aninhado sob o item de cima quando o marcador dele está recuado pelo menos duas colunas além do marcador desse item: dois espaços sob -, dois ou três sob 1. (a coluna em que começa o texto do item, como no CommonMark), até uma profundidade máxima de 5. |
| Lista ordenada | 1. item, 2) item | Algarismos seguidos de . ou ): algarismos europeus, ou os indo-arábicos (١.) e persas (۱.) que um teclado árabe ou persa digita. O número inicial é preservado (uma lista pode começar em 5, ou em 0). O separador que aparece na saída vem de orderedLists.separator, não do texto de origem. |
| Lista de tarefas (GFM) | - [ ] todo, - [x] done | Um item não ordenado com uma caixa de seleção entre colchetes. Aceita x minúsculo ou X maiúsculo. O motor desenha a caixa, com uma marca quando a tarefa está concluída; um caractere indicado em taskCheckboxChar / taskCheckedChar é composto como texto no lugar dela. |
| Fórmula em destaque | $$ … $$ | Uma fórmula LaTeX composta como bloco próprio. Sai centralizada na coluna, ajustada à grade de linhas de base como um título, e se mantém vetorial na saída em PDF. A forma de uma só linha e a forma delimitada, de várias linhas, são descritas em Fórmulas matemáticas. |
| Bloco de código | , ~~~ … ~~~ | Uma listagem, mantida como foi escrita: cada espaço, tabulação e quebra de linha, sem nada lido como Markdown. É composta linha a linha na fonte de código, dentro de uma caixa. Veja Blocos de código. |
Uma única linha em branco entre dois itens de lista é tolerada: a lista continua inteira. Duas ou mais linhas em branco encerram a lista.
Listas de tipos diferentes na mesma profundidade são aceitas (você pode passar de não ordenada para ordenada no meio da sequência), mas o motor trata cada trecho como separado para fins de numeração. Na prática, mantenha um único tipo por profundidade, a menos que tenha um motivo para misturá-los.
#Atributos de título
Uma linha de título pode terminar com um bloco de atributos entre chaves, com a mesma sintaxe key="value" das diretivas:
# The Long Road {author="I. Zango Martín" year=1998}As chaves e o conteúdo delas são retirados do texto do título (o título acima sai como The Long Road) e guardados no título como attrs. Eles ficam disponíveis para os espaços do design como marcadores {attr.<key>}: no espaço de design avançado do próprio título e nos cabeçalhos e rodapés de página, onde são resolvidos a partir do H1 do capítulo atual. Só é reconhecido um bloco balanceado, sem chaves internas, bem no fim da linha, depois de um espaço ou, já que os títulos em chinês são escritos sem ele, logo depois de um caractere chinês ou japonês (# 回目{style="x"}). O bloco só é aceito quando a sintaxe de atributos descrita abaixo consegue lê-lo inteiro: {x, y}, {紅樓|hóng lóu} e um {} isolado ficam no título, assim como atributos sem valor colados ao título (# 第一回{draft}). Os atributos são separados por espaços; por isso, um bloco com vírgulas ({a="1", b="2"}) e o {.class} do Pandoc também ficam no título. O identificador {#id} do Pandoc é lido: equivale a id="…" e identifica o título para as referências cruzadas. Uma chave escrita em outro sistema de escrita é lida e descartada com um aviso (veja abaixo); assim, # 回目{style="x" 作者=曹雪芹} ainda aplica style. Veja Configuração → Cabeçalhos e rodapés.
Um valor impresso por um texto do design pode ocupar várias linhas: os dois caracteres \n começam uma linha nova naquele ponto, qualquer que seja o overflow do elemento (to="Firma X\nStrasse 1\n10115 Berlin" imprime um endereço de três linhas). Com inlineMarks no elemento, as marcas em linha do valor também se aplicam: authors="Ana Ruiz^1^, Luis Gil^2^" compõe os números de afiliação como sobrescritos. Esse escape vale para os valores de atributo (e para os modelos do próprio design): os caracteres \n no texto de um título, por exemplo num trecho de código, são impressos como estão escritos.
Dois atributos têm significado próprio. style="<id>" aplica um estilo de título com nome ao título: um prefácio ou uma lista de autores com design de abertura, cabeços, geometria de página e tipografia de corpo próprios, e sem número de capítulo quando o estilo define numbered: false. toc="false" (ou "true") decide se o título aparece no :::toc:
# Preface {style="front-matter"}
# Contents {style="front-matter" toc="false"}Outros dois mudam o que um título imprime e como ele conta. hidden="true" (ou "false") substitui o hidden do nível ou do estilo do título: um título oculto não imprime nada e não ocupa espaço (no fluxo e também dentro de um boxe :::callout), mas continua abrindo a página dele, contando e aparecendo no sumário, nos cabeços {chapterTitle} e nos marcadores do PDF. jidori=N espaça por igual um título de uma linha até ocupar a largura de N caracteres dele (字取り: # 序章 {jidori=3} imprime 序 章), e jidori=0 desliga o espaçamento uniforme que o nível ou estilo dele define (veja Configuração › Valores por nível). indent=N desloca um título N caracteres do texto do corpo a partir do início da linha (字下げ: ## 一 {indent=5}), substituindo o indent do nível ou estilo dele; um número sem unidade conta ems do corpo, 0 põe o título no início da linha, e funciona igual em texto vertical e horizontal. firstLineIndent=N recua apenas a primeira linha de um título, substituindo o firstLineIndent do nível ou estilo dele, e as outras linhas começam onde indent as põe (os títulos da GB/T 9704: ## 关于加强管理的通知 {firstLineIndent=2}); lê os comprimentos como indent, e 0 desativa o do nível. startAt=N, um inteiro positivo, põe o contador de nível do título em N em vez de avançá-lo; os títulos seguintes continuam contando a partir daí, inclusive nos capítulos seguintes, e os níveis abaixo recomeçam sob ele como de costume. Com um estilo de título que numera apêndices com letras (numberingTemplate: 'Appendix {1:A}'), o primeiro apêndice reinicia a contagem para que se leia Appendix A em vez de continuar a partir dos capítulos:
# To my mother {hidden="true" toc="false"}
# Survey instrument {style="appendix" startAt=1}
# Raw data {style="appendix"}#Capitulares
Um parágrafo abre com uma capitular quando o nível ou o estilo do título correspondente, ou o estilo de parágrafo do grupo :::paragraphs a que ele pertence, define uma (veja Configuração › Capitulares): a primeira letra é composta em tamanho grande ao lado das primeiras linhas, que são encurtadas em volta dela. Não há marcação no próprio parágrafo; o texto é escrito como de costume, e a letra continua fazendo parte da palavra para a cópia, a busca e o mapa de origem. Um atributo dropcap a liga ou desliga num capítulo ou num grupo:
# Lost {dropcap=false}
# The mines {dropcap=2}
:::paragraphs{style="entry" dropcap}
The lamp of the first entry opens with an initial.
:::Na linha de um título, dropcap=false deixa o parágrafo depois desse título sem a capitular que o nível ou estilo do título define, dropcap=N a compõe sobre N linhas, e um dropcap sozinho dá uma a esse parágrafo (três linhas, a fonte do parágrafo) onde o nível não define nenhuma. Na linha de abertura de um :::paragraphs, o atributo faz o mesmo com o primeiro parágrafo do grupo, ou com todos os parágrafos quando o estilo define each: true. Para achar o parágrafo depois de um título, o Postext passa por cima de linhas de abertura e fechamento de contêineres, diretivas, boxes que saíram do fluxo e figuras flutuantes; um parágrafo dentro de um boxe, de um item de lista, de uma citação ou de um poema nunca leva capitular. Desde o postext 1.23.
Numa página composta os blocos são texto corrido: :::paragraphs{style="abertura" dropcap} num bloco abre o primeiro parágrafo dele com a capitular. Dentro de um boxe :::callout os parágrafos não levam nenhuma, e pedir uma ali gera um aviso dropCap.
#Blocos de código
Uma listagem vai entre dois delimitadores de três ou mais acentos graves (ou de três ou mais tis), cada um numa linha própria, com no máximo três espaços de recuo. Tudo o que fica entre elas é mantido como foi escrito: os espaços iniciais e as sequências de espaços, as tabulações, as linhas em branco e as linhas que começam com #, -, 1., >, $ ou :::. Nada do que está dentro é lido como Markdown: não há ênfase, :ref, fórmulas, chips, diretivas nem títulos. A linha de fechamento usa o mesmo caractere da linha de abertura e tem pelo menos o mesmo comprimento; por isso, uma listagem que mostra um delimitador vai dentro de um delimitador mais longo ou de tis:
```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copia as fotos para o disco de backup
rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/
echo "done: $(date)"
```A info string depois do delimitador de abertura indica a linguagem (na primeira palavra: js, ts, python, bash, console, json…), e o resto é lido como atributos na sintaxe de atributos, entre chaves ou soltos (title="app.js" lineNumbers). Qualquer outra coisa depois da linguagem é o título: ```console Terminal e ```python normalize.py imprimem Terminal e normalize.py sobre a listagem.
| Atributo | Efeito |
|---|---|
title="…" | Um título sobre a listagem, numa linha de título (ou numa aba de rótulo na borda da caixa, quando codeStyle.label está definido). |
label="…" | O texto da aba de rótulo da caixa, como o de um :::callout (com codeStyle.label). |
lineNumbers, lineNumbers=false | Numera as linhas desta listagem (ou não), independentemente do que define codeStyle.lineNumbers. Os números ficam numa coluna à parte, antes do código, e não são copiados com ele. |
start=N | O número da primeira linha (numera a listagem quando nada mais o faz). |
highlight="3,5-7" | Destaca com um fundo as linhas indicadas (contadas a partir da primeira linha da listagem, começando em 1): linhas soltas e intervalos, separados por vírgulas. |
span=page | Numa página de várias colunas, a listagem ocupa todas elas. |
placement=top, placement=bottom | Faz a listagem flutuar até a primeira faixa livre no topo ou no pé de uma coluna, como um :::callout flutuante. |
Um delimitador de abertura encerra o parágrafo de cima, com ou sem linha em branco, e o texto depois da linha de fechamento começa um parágrafo novo. Um bloco de código que fica aberto vai até o fim do texto, e o Postext gera o aviso unclosedCodeBlock. Um bloco de código dentro de um :::callout é um boxe aninhado nele; dentro de :::paragraphs, a listagem mantém o estilo de código, não o estilo de parágrafo. O Postext não tem continuação de item de lista; por isso, um bloco de código depois de um item de lista fecha a lista. As marcas de índice e as âncoras escritas dentro de uma listagem ficam como foram escritas.
O código recuado (quatro espaços ou uma tabulação, depois de uma linha em branco) só é lido como listagem quando codeStyle.indentedCode está ativado: os textos do Postext costumam recuar com espaços, e são os espaços iniciais que aninham os itens de lista.
A aparência de uma listagem (a fonte, a caixa, a largura da tabulação, o que acontece com uma linha mais larga que a caixa, os números de linha, as cores dos tokens) é definida por codeStyle; veja Configuração › Listagens de código. O código em linha (`x`) fica na fonte do texto, a menos que codeStyle.inline lhe dê outra. Um livro salvo antes do postext 1.23 que tenha esses delimitadores no texto continua lendo-os como antes, como Markdown (codeStyle.blocks: false). Desde o postext 1.23.
#O que NÃO é suportado
O Postext não reconhece os seguintes recursos do CommonMark. Eles são tratados como texto simples (e por isso aparecem literalmente na saída) ou descartados sem aviso:
- Títulos no estilo Setext: a forma sublinhada com
===/---. Use títulos ATX (#). - Passagem de HTML:
<tags>brutas não são interpretadas. Tags no estilo MDX também não são suportadas; o texto de origem do Postext é Markdown puro. - Linhas horizontais:
---,***,___. - Tabelas: tabelas com barras verticais não são analisadas. As tabelas são modeladas como recursos estruturados em
PostextContent.resources. - Links por referência:
[text][id]mais um bloco de definição. - Autolinks:
<https://example.com>. - Quebras de linha com dois espaços no fim: os espaços são removidos. Termine a linha com uma barra invertida (veja Quebras de linha).
- Notas de margem: não implementadas, e
PostextContent.notes, que os tipos aceitam, é ignorado pelo motor. As notas de rodapé e as notas de fim de capítulo são escritas com[^id](veja Notas de rodapé); até o postext 1.5, tinham de ser compostas como texto.
Esta lista vai diminuir com o tempo. Até lá, tudo o que não estiver listado explicitamente na seção de recursos suportados acima deve ser considerado texto literal.
Além da sintaxe, o árabe e as demais escritas da direita para a esquerda são compostos da direita para a esquerda, com o algoritmo bidirecional e encadernação à direita (veja Composição em árabe). O chinês é composto na horizontal e na vertical, com a quebra de linha, as larguras da pontuação, a justificação entre caracteres, as marcas, o rubi e o warichu que cada região espera (veja Composição chinesa). O japonês é composto com regras próprias: kinsoku, espaçamento dos yakumono, furigana, marcas de ênfase, marcas de kanbun e notas (veja Composição japonesa); o coreano passa pelo mesmo compositor com as regras do chinês continental. Há padrões de hifenização para oito idiomas, e rótulos embutidos para esses oito, para o chinês, o japonês e o árabe. Veja Idiomas e escritas.
#Convenções de escrita
Algumas convenções fazem a diferença entre um documento que é analisado sem problemas e um que surpreende você:
- Deixe uma linha em branco entre os blocos. Dois parágrafos separados por uma linha em branco são dois parágrafos. Dois parágrafos em linhas consecutivas viram um só: cada linha se junta ao parágrafo anterior.
- Linhas em branco a mais não acrescentam espaço. Três linhas em branco separam dois blocos exatamente como uma. Quando quiser mais espaço entre eles, escreva uma linha
:::space. - Recue um item aninhado até o texto do item de cima. Dois espaços sob um marcador (
-), três sob1., quatro sob10., como o CommonMark aninha as listas; dois espaços sob1.também aninham. Um item se aninha sob o item aberto mais próximo cujo marcador esteja pelo menos duas colunas à esquerda dele; assim, um espaço não aninha nada e um nível nunca é pulado, seja qual for o passo (até o postext 1.15, a profundidade erafloor(spaces / 2) + 1, e um1.sob1.saía no nível 4). Uma tabulação chega ao próximo múltiplo de quatro colunas. A profundidade máxima é 5. - Não recue o primeiro item da lista. Os itens de nível 1 começam na coluna 0. O primeiro item de uma lista abre o nível 1 por mais recuado que esteja (até o postext 1.15, os espaços iniciais aumentavam a profundidade); por isso, para aninhar é preciso haver um item acima.
- Os marcadores de tarefa devem estar entre colchetes com um único espaço.
[ ],[x],[X], sem variações.[*]ou[-]não são marcadores de tarefa; saem como texto literal. - Citações em bloco dentro de listas não são suportadas. Comece a citação na coluna 0, fora da lista.
- Imagens e tabelas ficam em
resources. Oem linha é removido justamente porque as imagens em linha atrapalham o posicionamento por colunas. Declare cada imagem como um recurso e faça referência a ela pelo id: o motor decide então se ela flutua, quebra a coluna ou passa para o alto da página seguinte. - Escape o cifrão com
\$quando não se tratar de matemática. O Postext interpreta$…$como LaTeX em linha; por isso, um$solto no texto abre uma fórmula. Preços, prompts de shell e qualquer outra coisa com um cifrão isolado devem ser escritos como\$. - Digite a marcação em ASCII, também em texto chinês e japonês. Um método de entrada chinês ou japonês gera formas de largura total:
:::num delimitador,#num título,[^1]num marcador de nota de rodapé,{…}em atributos,**para negrito. Elas saem impressas como texto, e a compilação sinaliza a linha com um avisofullwidthMarkupque indica a forma ASCII a digitar. Os valores dos atributos podem estar em qualquer escrita e entre“…”ou「…」; as chaves continuam em ASCII.
#Exemplo completo
Um documento curto que usa todas as construções suportadas:
---
title: The Typesetter's Craft
author: Anon
---
# Opening
A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.
## What makes text readable
Three properties matter most:
1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
1. Tighter at short measures.
2. Looser at long measures.
3. Contrast between body and headings.
Common failure modes include:
- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.
> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst
### Review checklist
- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread
### A note on formulas
Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$O mesmo documento, passado pelo motor de layout, produz um VDTDocument estruturado cujas páginas trazem cada um desses blocos como entradas tipadas; veja a página Arquitetura para saber como os blocos viram geometria.
#Exemplos nas Receitas
Receitas que usam o que esta página explica, cada uma sob a seção que mais lhe corresponde. Cada receita mostra as páginas ao lado do script completo.
Front matter
- Nº 012De uma string Markdown a uma página diagramada
- Nº 043Tradução lado a lado, estrofe por estrofe
- Nº 194Uma capa com janela que emoldura a folha de rosto
- Nº 195Um livro túnel com vinte folhas de fundo
- Nº 044Edição crítica: versos numerados e notas por verso
- Nº 005Cabeços pela paridade num livro de ensaios












