Formato do documento

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, então 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.

#Frontmatter

Um documento pode começar com um bloco opcional de frontmatter 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 frontmatter 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 frontmatter é lido com o gray-matter, então qualquer forma de YAML é aceita. O próprio Postext só olha title, subtitle, author e publishDate; as outras chaves ficam guardadas em PostextContent.metadata e são suas para usar como quiser.

O YAML dá tipos aos seus valores: 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 sua forma decimal simples, e um booleano como true ou false (title: 1984 imprime 1984). O YAML lê um número como valor, não dígito por dígito: 1.50 imprime 1.5, 017 (octal) 15, 1:30 (base 60) 90;
• uma data como o seu dia do calendário, escrito por extenso no idioma do documento (a configuração locale ou, na falta dela, o idioma da hifenização): publishDate: 2026-04-15 imprime 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-islamic imprime 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:00 são 04:30 UTC do dia 25 e imprime September 25, 2026;
• uma lista como os seus 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 seus dígitos, seja uma data que precisa manter o seu dia: publishDate: "15/04/2026", title: "1984". O texto chega a doc.metadata, aos marcadores de posição ({title}, {publishDate}…) e ao título e autor do PDF. Um dos quatro campos que não tenha forma de texto (um mapa aninhado, um title: vazio) 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.

#Construções de bloco

O Postext reconhece sete tipos de bloco de texto, além das diretivas e dos recursos incorporados descritos mais adiante nesta página. Um bloco sempre termina com uma linha em branco ou com o início de outro bloco.

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 seu conteúdo 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 de posição {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 flags soltas coladas ao título (# 第一回{draft}). Os atributos são separados por espaços, então 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 dá nome ao título para as referências cruzadas. Uma chave escrita em outra escrita é lida e descartada com um aviso (veja abaixo), então # 回目{style="x" 作者=曹雪芹} ainda aplica style. Veja Configuração → Cabeços 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, digamos em um 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 o seu próprio design de abertura, cabeços, geometria de página e tipografia de corpo, e sem número de capítulo quando o estilo diz 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 ainda abre a sua página, conta e aparece 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é a largura de N dos seus próprios caracteres (字取り: # 序章 {jidori=3} imprime 序　章), e jidori=0 desliga o espaçamento uniforme que o seu nível ou estilo define (veja Configuração › Ajustes por nível). indent=N desloca um título N caracteres do texto do corpo a partir do início da linha (字下げ: ## 一 {indent=5}), por cima do indent do seu nível ou estilo; 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. 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"}

#Diretivas

As diretivas são marcas de controle de uma linha, escritas como :::name ou :::name{attrs} em uma linha própria. Elas não produzem nada visível: comandam o posicionamento e a numeração.

Os valores dos atributos podem vir entre aspas duplas ("…"), entre aspas simples ('…') ou sem aspas (startAt=17). Uma chave sem = é tratada como uma flag presente, mas vazia.

Hoje só pagebreak, numbering, columnbreak, space, toc e index são reconhecidas como diretivas de uma linha (e references, verse, page e strip como blocos entre cercas); qualquer outra linha :::name que não seja um contêiner (veja abaixo) é lida como parágrafo e gera um aviso Diretiva desconhecida no Sandbox. O motor também a registra, como uma entrada unknownDirective nos contentWarnings do documento (veja Configuração › Avisos no documento).

#Valores de atributo

A mesma sintaxe key="value" é lida nos atributos de título, nas cercas de diretivas e contêineres (:::name{…}), nas referências em linha (:ref{…}), nos chips (:chip[…]{…}), nas amostras de cor (:swatch{…}) e nas marcas de índice (:index[…]{…}). As regras:

• Chaves. Começam com uma letra ASCII ou _ e continuam com letras ASCII, algarismos, _ ou -. Espaços em volta do = não atrapalham, o ＝ de largura total que um método de entrada chinês digita funciona como =, uma chave repetida fica com o último valor, e uma chave sem = é uma flag com valor vazio. Uma chave em outra escrita (作者=曹雪芹) não é lida e gera um aviso attributeKeyInvalid; as outras chaves do bloco continuam valendo. Os valores podem estar em qualquer escrita.
• Valores entre aspas. Um valor entre aspas duplas pode conter qualquer coisa menos ", inclusive aspas simples; um entre aspas simples, qualquer coisa menos '. Assim, um valor com aspas duplas vai entre aspas simples: lead='He said "hi"'. Não há escapes (a barra invertida é um caractere comum), então um valor que precisa dos dois tipos de aspas ASCII usa aspas tipográficas (“…”, ’). Um valor também pode abrir com a aspa curva “ ou com o colchete de canto 「 que um método de entrada chinês digita, e então vai até o ” ou 」 correspondente, com espaços: title=“甲戌本 眉批”, title=「脂批」.
• Valores sem aspas (startAt=17, year=1998) vão até o próximo espaço: title=Hello world é title="Hello" mais uma flag world.
• Sem chaves. { e } nunca entram em um valor. A primeira } encerra o bloco: uma cerca cujo valor contenha uma deixa de ser diretiva e vira parágrafo, e em linha o resto do valor vaza para o texto. Em um título, uma chave dentro de um valor deixa o bloco inteiro no título: # Title {note="a {b"} sai como está escrito. (Até o postext 1.8, uma { depois de um espaço recomeçava o bloco e b era lido como flag.)
• O cifrão é texto comum. Os atributos são lidos antes das fórmulas em linha, então lead="from $5 to $6" é só texto.
• Uma linha. Um bloco de atributos nunca ocupa mais de uma linha.

# The Long Road {lead='A "road novel", they said' price="$18"}
 
:::callout{type="note" title='The "fast" path'}
…
:::

::resource{id="…"} é mais rígido: o id entre aspas duplas e nenhum outro atributo (veja Recursos).

#Contêineres

Um contêiner envolve uma sequência de blocos entre cercas: uma linha de abertura :::name ou :::name{attrs}, depois qualquer conteúdo comum (parágrafos, títulos, listas, citações, fórmulas, até outras diretivas) e uma linha de fechamento só com :::. Os contêineres podem ser aninhados; cada ::: de fechamento fecha o mais interno que estiver aberto.

:::callout{type="note"}
Keep the lantern lit **every** night.

- Check the wick.
- Trim it at dusk.
:::

Quatro nomes de contêiner são reconhecidos no fluxo do texto (um quinto, :::columns, só funciona dentro de um boxe e é descrito abaixo). O que cada um produz é definido na sua própria seção da configuração:

Os atributos que cada contêiner aceita, e como ele é estilizado, estão documentados em Configuração. Os valores dos atributos seguem a mesma gramática das diretivas. Uma cerca :::callout aceita type (o id de um estilo de boxe configurado; tipos desconhecidos ou ausentes recaem no primeiro estilo), title (substitui o título padrão do estilo) e span / placement (column, page ou side; here, top, bottom ou fixed) para substituir a extensão e a posição do estilo naquele boxe:

:::callout{type="objectives" title="What you will learn" span="page" placement="top"}
- Name the parts of the lantern.
- Trim the wick without touching the glass.
:::

Um boxe flutuante (placement auto, top ou bottom) também aceita columns, o número de colunas vizinhas que ele ocupa em uma página com várias, como em :::callout{placement="top" columns="2"} (desde o postext 1.18).

Um boxe é diagramado como uma caixa: um título opcional e, depois, o conteúdo composto com a tipografia de corpo e de listas do próprio estilo. Por padrão ele se mantém inteiro e passa completo para a coluna ou página seguinte quando não cabe (um boxe mais alto que uma coluna inteira é dividido mesmo assim, em vez de transbordar); um estilo com keepTogether: false permite dividi-lo entre os seus blocos, ou entre linhas, deixando pelo menos splitMinLines linhas de texto (ou uma figura, tabela, fórmula destacada ou boxe aninhado) de cada lado do corte (um corte dentro de um parágrafo ou item de lista também deixa pelo menos layout.boxChildSplitMinLines das suas linhas de cada lado: duas por padrão, ou splitMinLines quando esse valor é menor; livros salvos antes da 1.5 cujos capítulos têm um boxe são lidos com 1, o corte da 1.4). Cada parte depois da primeira abre sem o ícone, embora o texto mantenha a coluna do ícone, e sem o título, a menos que o estilo o repita (repeatTitle: “Pontos-chave (cont.)”); um estilo também pode pôr uma marca de “Continua” sob cada parte que prossegue (continuesMarkerEnabled); veja Marcas em um boxe dividido. Os boxes de largura total (span="page") cortam a página em faixas de colunas; os boxes span="side" saem do fluxo para a coluna lateral só de flutuantes de um layout de coluna e meia (layout.sideColumnRole: 'floats'), empilhados ao lado do texto que interrompem, e são diagramados como boxes de coluna onde essa coluna não existe; os boxes placement="fixed" saem do fluxo e ficam presos a coordenadas da página (um selo de autoavaliação no canto inferior esquerdo da última página de um capítulo, por exemplo), e as colunas que eles cobrem cedem essa zona; os boxes flutuantes (placement="top" / "bottom") saem do fluxo onde aparecem e ocupam a primeira faixa livre depois dessa posição (o pé da página, ou a cabeça ou o pé da seguinte), enquanto o texto que vem depois deles preenche a página que deixaram. Um estilo com floatBarrier: true (tipicamente o boxe de “pontos-chave” que fecha um capítulo) transforma o boxe em uma barreira de flutuantes: toda figura ou tabela referenciada antes dele é posicionada antes dele (nos espaços livres da página, ou em páginas abertas antes do boxe), para que nenhum flutuante escape para depois do fim do seu capítulo. Uma cerca :::name desconhecida não é um contêiner: a linha é tratada como texto, exatamente como uma diretiva desconhecida.

Uma cerca :::part aceita number (como você quer que ele seja impresso: "I", "IV", "3"; ele também é interpretado para que o design possa reformatá-lo) e title; os dois são opcionais. Um terceiro atributo, palette="band=#hex" (vários pares id=#hex, separados por vírgulas), recolore todas as cores do design ligadas a esses ids da paleta (cabeços, faixa de abertura, designs de parte) e as cores do fluxo de texto que compartilham o mesmo valor de base (títulos, negrito, referências, marcadores, legendas, tabelas, boxes, chips) na parte e nos capítulos que vêm depois dela, até a parte seguinte; veja Configuração › Partes. O contêiner sempre abre uma página própria: uma quebra de página com a paridade configurada antes dele, uma única coluna de corpo com as margens parts.margins, o design de abertura sobre a página inteira e outra quebra de página depois da cerca de fechamento. O corpo (geralmente a lista dos capítulos que a parte reúne, ou nada) é composto com parts.bodyStyle:

:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
:::

# The lantern and its parts

Com as configurações de título padrão, isso produz a sequência clássica: página de parte em uma página à direita, página em branco à esquerda e capítulo na página seguinte à direita. A página é marcada como role: 'part', para que cabeçalhos e rodapés possam pulá-la, e {partTitle} / {partNumber} se resolvem com a parte atual em todas as páginas seguintes. Veja Partes na referência de configuração.

Uma cerca não precisa de uma linha em branco antes dela: uma cerca de abertura ou de fechamento colada logo abaixo de um parágrafo, lista ou citação encerra esse bloco. Um contêiner que fica aberto no fim do documento é fechado automaticamente ali, e o Sandbox mostra um aviso Contêiner não fechado apontando para a linha de abertura. Um ::: solto, sem contêiner aberto, fica no texto como um parágrafo visível em vez de ser descartado sem aviso.

#:::columns

Dentro de um :::callout, um grupo :::columns{count=2} … ::: compõe os blocos entre as suas cercas em count colunas de mesma largura (separadas pelo columnGap do estilo): a sequência é cortada onde as colunas ficam mais niveladas (entre blocos, ou entre as linhas de um parágrafo ou item de lista, cujo final continua no topo da coluna seguinte sem o marcador), e o boxe cresce até a altura da coluna mais alta. Os blocos depois do grupo voltam a ocupar a largura inteira. Fora de um boxe, as cercas são ignoradas e os blocos fluem normalmente. Um atributo breaks fixa o início das colunas em vez de balanceá-las: :::columns{count=2 breaks="4"} abre a segunda coluna no quarto bloco do grupo (uma lista separada por vírgulas para mais colunas), sem corte dentro de um parágrafo: uma coluna de texto ao lado de uma coluna de figura.

:::callout{type="summary"}
:::columns{count=2}
- Every element is one kind of atom.
- Electrons live in orbitals.
- A bond shares or transfers electrons.
:::
:::

Como breaks conta. breaks numera os blocos do grupo em ordem (parágrafos, itens de lista, um bloco cada, fórmulas destacadas, figuras e tabelas), e um :::callout aninhado conta como um bloco, por mais blocos que contenha. As diretivas não são blocos: um :::space entre duas estrofes não altera a contagem. Um número menor que 2, além do último bloco do grupo ou que não venha depois da quebra anterior é ignorado. Dentro de um grupo, :::space separa dois blocos como em qualquer outro ponto de um boxe, e some no topo do grupo e no topo de cada uma das suas colunas (uma posição de breaks ou um corte de nivelamento); para abrir o grupo mais abaixo, ponha o espaço antes da cerca :::columns. Assim, duas colunas com o mesmo espaçamento ficam alinhadas estrofe por estrofe:

:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,
 
and trimmed before the dawn.
 
:::space
 
The keeper sleeps by day.
 
La lámpara se enciende al anochecer,
 
y se despabila antes del alba.
 
:::space
 
El farero duerme de día.
:::
:::

Aqui o quarto bloco, “La lámpara…”, abre a segunda coluna; as duas linhas :::space não são contadas e deixam o mesmo espaço nas duas colunas.

Uma cerca :::callout também aceita label="…": o texto que um estilo com uma aba label imprime no canto superior do boxe (:::callout{type="box" label="BOX 1-1" title="The octet rule"}).

Um :::callout dentro de outro é um boxe próprio: um cartão de exercícios com caixas de resposta, por exemplo. Ele usa o seu próprio estilo (fundo, borda, raio, preenchimento interno, título, ícone) na largura interna total do boxe externo e se empilha entre os outros blocos dele; o seu span e o seu placement são ignorados, já que um boxe aninhado sempre flui dentro do boxe pai. Cada cerca fecha o boxe mais interno ainda aberto:

:::callout{type="card"}
The statement of the exercise.
 
:::callout{type="answer"}
A white answer box with its own border and padding.
:::
 
:::callout{type="answer"}
A second answer box.
:::
:::

Quando o boxe externo é dividido entre colunas ou páginas (keepTogether: false, ou mais alto que uma coluna), um boxe aninhado passa inteiro para o fragmento seguinte, a menos que o seu próprio estilo também permita dividi-lo; cada fragmento redesenha as molduras que contém, e um boxe aninhado que continua perde o ícone e também o título, a menos que o seu estilo o repita (repeatTitle).

#:::paper

Um livro pode trocar de papel em uma sequência de páginas: um caderno de pranchas em couché brilhante em um livro impresso em papel não revestido, um encarte em cartão, algumas folhas de papel colorido. Envolva esse conteúdo em um contêiner :::paper:

:::paper{type=coatedGloss grammage=130}
## Plates
::resource{id="plate-1"}
::resource{id="plate-2"}
:::

Um papel cobre folhas inteiras, então o conteúdo entre as cercas começa em uma página nova, e o que vem depois do ::: de fechamento também começa em uma página nova. Uma sequência que encerra o documento não deixa página em branco depois dela. As figuras e tabelas citadas dentro da sequência são posicionadas antes que ela se feche. Cada página composta com conteúdo de dentro do contêiner leva o papel no layout (VDTPage.paper, com os atributos como a cerca os escreve); as páginas de fora não levam nada. O visualizador Folio lê essa informação e desenha essas folhas com a cor, a superfície, a espessura e a rigidez do papel. As saídas em canvas, PDF e HTML a ignoram: as páginas são compostas e impressas como qualquer outra.

Os atributos são os das configurações folio.paper, e todos são opcionais. Um atributo que a cerca omite segue o papel do documento e, na falta dele, os valores padrão do tipo de papel:

Um :::paper dentro de outro só substitui os atributos que define, e também começa e termina com uma quebra de página. Dentro de um :::callout, as cercas são ignoradas. Um valor que o motor não consegue ler é descartado, e o Sandbox o lista como um aviso Atributo de papel inválido (paperAttributeInvalid nos contentWarnings do documento).

#:::pagebreak

A diretiva sozinha não impõe paridade; ela só afeta a diagramação do bloco seguinte. Use-a para encerrar um prefácio, levar uma dedicatória para uma página própria ou marcar o fim de uma seção. Quando você quer uma quebra de página e um reinício da numeração no mesmo ponto, combine :::pagebreak seguido de :::numbering: a troca de numeração se aplica à página nova que o :::pagebreak acabou de criar.

Uma quebra de página em uma página ainda vazia não faz nada, então nunca acrescenta uma página em branco. Ela também não substitui o breakBefore de um título logo depois dela (o nível 1 tem um por padrão): o título ainda aplica a sua paridade, o que pode acrescentar uma página em branco depois da que a diretiva abriu. Para começar um título exatamente ali, desligue a quebra dele (veja Configuração → Estilos de título). Depois de um título de capa que preenche a sua página, a quebra é opcional: a capa já ocupa o resto da página, em layouts de uma ou de várias colunas, e um :::pagebreak logo depois dela não atrapalha. Ela só é necessária depois de uma capa cujo design para antes do pé da página, quando o texto ainda deve começar na página seguinte (veja Configuração → Altura reservada).

The old chapter ends here.
 
:::pagebreak{parity="odd"}
 
# A new chapter

A flag center (:::pagebreak{center}, desligada com center=false) centraliza o texto da página que a quebra abre entre a cabeça e o pé da mancha, e no sentido da largura em texto vertical: a ページの左右中央 de um título de parte ou de uma dedicatória em japonês. Os flutuantes, as notas e os cabeços ficam onde estão, e uma página já cheia não é alterada. A flag não encerra a página: feche-a com outro :::pagebreak.

:::pagebreak{center}
 
# 上　先生と私
 
:::pagebreak

Atributo de paridade

O atributo parity aceita os mesmos cinco valores que headings.levels[*].breakBefore.parity:

• 'any': o padrão; sem restrição de paridade, a quebra simplesmente abre uma página nova.
• 'odd' / 'even': a página nova abre no lado pedido da página dupla; uma única página em branco só é inserida quando a página seguinte natural cai no lado errado.
• 'always-odd' / 'always-even': garantem pelo menos uma página separadora em branco obrigatória entre o conteúdo anterior e a página nova, e depois impõem a paridade. A página separadora pertence ao capítulo anterior; qualquer página de preenchimento a mais, por paridade, pertence ao que vem depois.

A quem pertence a página em branco

Os dois tipos de página em branco que :::pagebreak (e breakBefore) podem introduzir são diferenciados no modelo VDTPage:

• blankForParity: true: inserida para cumprir uma restrição de paridade. Nos cabeçalhos com {chapterTitle}, essa página leva o título do capítulo seguinte, porque a página em branco só existe para empurrar esse capítulo para a paridade certa.
• blankForForce: true: o separador inicial obrigatório de um modo 'always-*'. Ela pertence ao capítulo anterior: uma pausa deliberada no fim do capítulo, não um preenchimento de paridade para o capítulo seguinte.

As mesmas duas regras dão a uma página em branco os cabeços e a paleta de uma seção com estilo; veja Configuração › Estilos de título.

Exceção no início do documento

Quando :::pagebreak é a primeira construção do documento (ou quando um título com breakBefore traria uma), a imposição de paridade é ignorada enquanto a primeira página ainda está vazia. O bloco seguinte cai na página 1 como foi escrito, qualquer que seja a paridade pedida, sem uma página em branco inicial indevida.

#:::numbering

:::numbering é o jeito de reiniciar o contador de páginas no meio do documento. O exemplo clássico de livro:

---
title: "A Book With Front Matter"
---
 
# Preface
 
…
 
:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}
 
# Chapter 1

As páginas do prefácio são numeradas i, ii, iii, …; o primeiro capítulo abre em uma página à direita numerada 1.

Mudanças só de formato (sem startAt) mantêm o contador correndo; isso serve, por exemplo, para passar de lower-alpha para upper-alpha sem reiniciar.

format aceita qualquer grafia de um formato de numeração: roman-lower e i funcionam tanto quanto lower-roman, arabic tanto quanto decimal, 一 e あ tanto quanto japanese-informal e hiragana (veja Configuração › Grafias dos formatos de numeração). Um valor que não seja nenhum deles deixa o formato como estava, e o Sandbox o sinaliza.

#:::space

:::space deixa um espaço vertical entre dois blocos: para separar uma linha de fecho do texto acima, para descer um pouco uma epígrafe ou uma assinatura, ou para abrir uma quebra de cena (um espaço em branco) entre dois trechos de texto. Linhas em branco a mais no Markdown não fazem isso: como em qualquer Markdown, uma sequência de linhas em branco é apenas um separador de parágrafos, o que evita que um documento mude de diagramação quando um editor ou formatador acrescenta ou apara espaços em branco.

The last paragraph of the scene.
 
:::space
 
A new scene begins one line lower.
 
:::space{lines=2}
 
Two lines lower still.

• lines: quanto espaço, em linhas de corpo (a grade de linhas de base). O padrão é 1. Números inteiros mantêm todas as linhas de texto na grade, então as colunas continuam alinhadas na página; uma fração (lines=0.5) é respeitada exatamente, à custa desse alinhamento até o próximo bloco que se ajuste à grade. Um valor que não seja um número maior que 0 e no máximo 20 volta a uma linha, e o Sandbox o sinaliza (Tamanho de espaço inválido).
• Ele se soma. O espaço é acrescentado à margem que já separa os dois blocos (a margem superior de um título, a margem inferior de uma lista), em vez de se fundir com ela. Duas linhas :::space seguidas somam duas linhas.
• Ele é descartado em uma quebra, como o \vspace do LaTeX: no topo de uma coluna ou página ele some, para que uma página nunca abra com um buraco; e quando não cabe no pé de uma coluna, simplesmente encerra essa coluna, sem levar o resto adiante.
• O parágrafo seguinte sai sem recuo. Quando bodyText.indentAfterHeading está desligado, um parágrafo logo depois de :::space perde o recuo de primeira linha, como acontece depois de um título: a convenção habitual para o texto que recomeça depois de uma linha em branco.
• Dentro de um boxe (ou de um grupo :::columns), ele separa os filhos do boxe da mesma forma, medido nas linhas de corpo do próprio boxe. Antes do primeiro bloco do boxe ele é descartado, como no topo de uma coluna (o preenchimento interno já afasta o conteúdo da moldura), exceto em dois casos em que ele abre esse espaço: logo abaixo do título do boxe, e em um boxe que não contém mais nada (uma caixa de resposta, um espaço para escrever, medido em linhas). Ele sempre some no topo de um grupo :::columns, no topo de cada uma das suas colunas e no topo da parte de um boxe dividido que continua na coluna ou página seguinte. Dentro de um contêiner :::paragraphs, funciona como entre parágrafos do corpo.
• O manter com o seguinte leva ele em conta: um título seguido de :::space passa adiante quando o espaço e as primeiras linhas do seu texto não cabem abaixo dele.

A caixa de resposta de uma folha de exercícios é um boxe cujo único conteúdo é espaço: a pergunta no título e quatro linhas livres abaixo.

:::callout{type="answer" title="1. Name the three parts of the lantern."}
:::space{lines=4}
:::

Para uma quebra fixa em vez de espaço, use :::columnbreak ou :::pagebreak.

#:::verse

Um poema na disposição árabe clássica (uma qaṣīda, uma qiṭʿa): cada verso, o bayt, em uma linha dividida em duas metades, o ṣadr no lado de início (a direita, em árabe) e o ʿajuz no lado de fim, com um espaço entre eles. Escreva um bayt por linha, com os hemistíquios separados por || (um \\ com um espaço de cada lado, como nos textos do Wikisource, também funciona). Uma linha sem separador é um hemistíquio único, centralizado no poema.

فأنشد يقول:
 
:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::

• Uma largura. Todos os hemistíquios do poema são compostos com uma mesma largura, então cada ṣadr começa na mesma vertical e cada ʿajuz termina em outra, e as letras da rima ficam alinhadas ao longo do poema. A largura é a do hemistíquio mais largo, no máximo metade da medida menos o espaço central; width a define (width=55mm). Cada hemistíquio é levado a essa largura primeiro com kashidas (o verso alonga mais que a prosa: o dobro de bodyText.kashidaMaxLength) e depois com os espaços entre palavras; um hemistíquio de uma só palavra que não consiga preenchê-la deixa o resto no espaço central.
• O espaço central é de 2 em por padrão; gap o define (gap=3em; um número sem unidade é em ems). ornament imprime uma marca no meio dele (ornament="٭"), que não faz parte do texto.
• Largo demais. Um hemistíquio mais largo que a largura comum primeiro aperta os espaços entre palavras até bodyText.minWordSpacing. Se ainda não couber, o seu bayt é composto em escada: o ṣadr encostado no lado de início em uma linha própria, o ʿajuz encostado no lado de fim na linha seguinte.
• Posição. O poema fica centralizado na coluna; align=start o encosta no lado de início. Um bayt nunca é dividido entre colunas ou páginas, e o poema segue as regras de órfãs e viúvas dos parágrafos (um poema de três bayts ou menos fica inteiro). O parágrafo antes do poema, que o introduz («فأنشد يقول:»), mantém a sua última linha junto com os primeiros bayts.
• Tipo. O poema usa a família, o tamanho e a entrelinha do texto do corpo; style dá o nome de um estilo de parágrafo para ele (style="verse"), e é assim que um poema vocalizado ganha a entrelinha extra de que os seus harakat precisam. dir=ltr ou dir=rtl define a sua direção como em qualquer bloco; um poema em escrita latina em um livro da esquerda para a direita tem o ṣadr à esquerda.

O texto simples do poema mantém os hemistíquios e os bayts separados (uma tabulação e uma quebra de linha), então uma busca ou um trecho copiado o lê como foi escrito; as kashidas e o ornamento ficam de fora.

#:::toc

:::toc imprime o sumário onde está. Ele se expande em blocos comuns (um por título dos níveis que toc.levels lista, o nível 1 por padrão, e um por :::part), então o sumário flui por colunas e páginas como qualquer outro texto, e um clique em uma entrada leva à linha da diretiva. Uma entrada mostra o número do título (o resultado do seu numberingTemplate ou, na falta dele, o ordinal do capítulo), o título, uma linha de pontos e o rótulo da página em que ele começa e, quando toc.subtitle está ativado, uma segunda linha com um atributo de título, como o {author="…"} do capítulo. Uma parte ganha uma linha própria, desenhada por toc.parts.design e colorida com a palette da própria parte. Os títulos cujo estilo tem numbered: false aparecem sem número; {toc="false"} em um título o deixa de fora (tipicamente, o título do próprio sumário).

# Contents {style="front-matter" toc="false"}
 
:::toc

Os números de página são os que o documento realmente imprime. Um documento diagramado sozinho é diagramado de novo com os rótulos da passada anterior até que eles parem de mudar; com a numeração reiniciando depois dos elementos pré-textuais (a receita de :::numbering acima), uma passada extra resolve. Um capítulo diagramado sozinho (as visualizações do Sandbox) recebe, em vez disso, o esquema do livro inteiro da aplicação que o hospeda. Veja Sumário na referência de configuração.

#:::index

:::index imprime o índice remissivo onde está: os termos marcados com :index[…] ou :index{term="…"} ao longo do livro, com as suas páginas, que acompanham o texto quando ele se move. Ele é descrito junto com as marcas em Índice remissivo.

# Index {style="index"}
 
:::index

#Quebras de linha em títulos

Escreva \\ dentro de um título (ou dentro do atributo title de uma parte) para forçar uma quebra de linha onde o título é exibido como título: o título na coluna continua fluindo e mostra um espaço ali, enquanto o {titleText} de um design de abertura quebra a linha nesse ponto (em todos os modos de overflow do elemento de texto). Os cabeços, {chapterTitle}, {partTitle} e o sumário do PDF sempre mostram o título em uma linha. Em chinês ou japonês, a quebra é lida como um espaço ideográfico entre dois caracteres da escrita (um título em dístico); onde um deles encontra um algarismo ou texto latino (关于举办 \\ 2026年…), a página aplica o espaço entre han e latino, e os marcadores do PDF e o título do documento juntam as duas metades sem nada entre elas, como se escreve o chinês simples.

# Concepts of health and illness. \\ Community health {author="I. Zango Martín"}

#Formatação em linha

A marcação em linha é reconhecida dentro de qualquer bloco de texto (títulos, parágrafos, citações em bloco, itens de lista). Num título ela segue headings.inlineMarks, ativado por padrão: o itálico, o negrito, os sobrescritos e subscritos, os versaletes e os links do título saem impressos como num parágrafo, e um trecho em itálico dentro de um título em itálico sai em redondo. Com a opção desativada, os marcadores são descartados e o título sai no estilo do próprio título; é assim que se leem as configurações salvas pelo postext 1.4 ou anterior cujos títulos tenham marcas (veja Configuração › Títulos). O design de um título imprime {titleText} como texto simples em qualquer caso.

Marcação	Sintaxe	Observações
Negrito	negrito ou negrito	Renderizado com bodyText.boldFontWeight. Um bodyText.boldColor opcional substitui a cor padrão do corpo nos trechos em negrito.
Itálico	itálico ou itálico	Renderizado com a variante itálica da família tipográfica atual. Um bodyText.italicColor opcional substitui a cor padrão do corpo nos trechos em itálico. O sublinhado marca ênfase só num limite de palavra, como no CommonMark: entre duas letras ou dígitos (snake_case_name, o SR_AIR_EN.pdf de uma URL) ele é texto (o mesmo vale para bold); dentro de uma palavra, use asteriscos (unbelievable). Letras chinesas, japonesas e coreanas não contam aqui, já que essas escritas não têm espaços: 中文_斜体_中文 e 中文__粗体__中文 saem em itálico e em negrito. Um __ que não forma negrito nunca vira itálico: foo__bar__baz continua texto.
Negrito itálico	ambos ou ambos	As duas marcas se combinam.
Sobrescrito	^texto^	Composto a 58% do tamanho do texto e elevado um terço dele: um expoente (10^-8^), a carga de um íon (Na^+^). O texto marcado começa e termina com um caractere que não é espaço; um acento circunflexo solto na prosa continua literal, assim como as carinhas ^_^ e ^o^ (n.^o^ e 1^o^ continuam sendo sobrescritos).
Subscrito	~texto~	Mesmo tamanho, rebaixado 0,15 do tamanho do texto para ficar dentro das descendentes: o índice de uma fórmula química (H~2~O, pK~a~). Um til com um dígito de cada lado é um intervalo e continua literal: 3~5 days, 需要3~5天. O mesmo vale para um til entre duas palavras chinesas, que não abre subscrito: 周一~周五, 北京~上海; um subscrito ainda se fecha antes de um caractere chinês (F~合~等于). Combina com negrito e itálico (H~2~O). Um subscrito e um sobrescrito escritos juntos, sem nada entre eles, ficam empilhados como numa fórmula: T~0~^2^ põe o 2 sobre o 0, seja qual for o primeiro, com o subscrito rebaixado 0,25 do tamanho do texto para não bater no sobrescrito, e o par ocupa a largura do mais largo. Um espaço ou uma letra entre eles os compõe um depois do outro; um word joiner (U+2060) também, sem nada visível entre eles. Um par empilhado nunca se separa numa quebra de linha: uma palavra larga demais para a linha quebra antes do par.
Versaletes	:smallcaps[texto]	Letras minúsculas compostas como maiúsculas a 70% do tamanho do texto: o nome de uma personagem numa peça de teatro, uma sigla no texto corrido. Aceita outras marcas dentro e em volta; veja Versaletes.
Orientação no texto vertical	:tcy[12], :upright[GDP], :sideways[12]	No texto vertical: uma única célula em pé (tate-chu-yoko), cada caractere em pé numa célula própria, ou o trecho inteiro girado. Não têm efeito no texto horizontal; veja Orientação no texto vertical.
Marcas chinesas	:dots[不可], :name[賈寶玉], :book[石頭記]	Pontos de ênfase (着重号), a linha de nome próprio (专名号) e a marca de título de obra (书名号: 《》 ou uma linha ondulada, conforme cjk.bookTitleMark). O texto fica como foi escrito; veja Marcas chinesas, rubi e warichu.
Rubi	:ruby[紅樓]{rt="hóng lóu"} ou {紅樓|hóng|lóu}	Leituras em pinyin ou zhuyin sobre (ou ao lado de) os caracteres-base. A forma compacta exige uma base em han, kana ou bopomofo, de modo que {x|x>0} continua texto.
Warichu	:warichu[nota]{open="〔" close="〕"}	Uma nota composta em duas linhas de meio corpo dentro da linha (双行夹注), quebrada entre linhas e páginas.
Código em linha	code	Os acentos graves são removidos; o trecho é renderizado como texto simples, exatamente como foi escrito: um , um chip, uma fórmula, um link ou um marcador de ênfase dentro dele sai literal, e é assim que um texto mostra a sintaxe. Um estilo próprio para código está no roadmap.
Escape	, , , , ,	Uma barra invertida compõe o próprio caractere marcador (o asterisco de uma nota de tabela, , um circunflexo literal, um cifrão que não abre fórmula) em vez de abrir um trecho. Funciona no corpo, nos chips e em legendas, células e notas. (Até o postext 1.4, legendas, células, notas e chips imprimiam a barra invertida de .)
Espaço inseparável	o próprio caractere: U+00A0, U+202F, U+2007	Cola as palavras de um lado e do outro, de modo que a linha nunca quebra entre elas: um número e sua unidade (37 °C), uma referência de página (p. 12), um grupo de milhares (225 000). O espaço inseparável (U+00A0), o espaço inseparável estreito (U+202F) e o espaço de algarismo (U+2007) colam todos (no corpo, em legendas, células, boxes e cabeços) e cada um mantém sua própria largura: a justificação estica só os espaços entre palavras. Muitas fontes não têm glifo para o espaço inseparável estreito nem para o espaço de algarismo; nesse caso eles são compostos como os navegadores os compõem, no canvas, no HTML e no PDF igualmente: meio espaço de palavra e a largura de um dígito. Praticamente toda fonte tem U+00A0, então ele é a escolha segura. Um grupo colado assim que seja mais largo que a linha inteira quebra no seu último espaço inseparável, e não dentro de uma palavra. O word joiner (U+2060) cola sem ocupar espaço. Digite o próprio caractere: uma entidade HTML como sai impressa como foi escrita. Veja Onde uma linha nunca quebra.
Link	texto	O texto visível fica no fluxo, composto exatamente como seria sem o link. A URL transforma as palavras num link ativo no HTML e no PDF; veja Links.
Imagem		O Markdown de imagem em linha é removido do texto. As imagens precisam ser declaradas em PostextContent.resources para que o motor de layout possa posicioná-las segundo as regras de resourcePlacement.
Chip	:chip[texto]	Um trecho de texto dentro de uma caixa que quebra como uma unidade só: um banco de palavras, uma tecla, uma etiqueta. Estilizado por chipStyles; veja Chips em linha.
Fórmula em linha	$…$	Uma fórmula LaTeX que flui com o texto em volta, por exemplo $e^+1=0$. Composta pelo MathJax e renderizada como contornos vetoriais em todos os renderizadores. Use \$ para um cifrão literal. A escala, a forma destacada ($$ … $$) e o tratamento de erros estão em Fórmulas matemáticas.

#Links

Um link Markdown, [text](url), mantém o texto no fluxo exatamente como ele seria composto sem o link: o link nunca altera quebras de linha, espaçamento nem cor. Ele guarda a URL para as saídas capazes de segui-la:

• HTML (renderToHtml): as palavras com link ficam envolvidas em <a href="…" rel="noopener noreferrer">, que herda a cor do texto e não tem sublinhado. Há uma âncora por trecho de palavras com link em cada linha.
• PDF (postext-pdf): cada trecho de palavras com link numa linha vira uma anotação de link URI clicável. Num PDF com tags, é um elemento Link cujo texto são as palavras com link.
• Canvas: pintado como texto simples, já que um canvas não tem superfície de clique.

Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration")
or write to [the team](mailto:team@example.com).

• O destino pode trazer um título, que é ignorado ([text](https://example.com "Title")). Também pode vir entre sinais de menor e maior, e nesse caso os espaços viram %20 ([text](<https://example.com/a b>)).
• Só destinos seguros são mantidos: http:, https:, mailto:, tel:, ftp: e URLs relativas (../guide, #top). Qualquer outro esquema (javascript:, data:, file:…) compõe o texto sem link. O PDF só cria links para URLs absolutas.
• O destino pode conter parênteses, desde que estejam balanceados, como no CommonMark: [photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg) liga a URL inteira. Uma barra invertida escapa um caractere (\(, \_). Quando os parênteses não se balanceiam, o destino termina no primeiro ) e o texto é composto sem link; codifique um parêntese solto como %28 ou %29. Um espaço também encerra o destino, a menos que ele esteja entre sinais de menor e maior.
• Uma palavra colada ao texto do link compartilha o link. Em see [the site](https://example.com). o ponto final faz parte da área clicável.
• O texto do link pode ter ênfase ([**bold** words](…)) e pode estar dentro dela (**[words](…)**).
• Os links funcionam em parágrafos, itens de lista, citações em bloco, boxes, legendas, notas e células de tabela, e em títulos enquanto headings.inlineMarks estiver ativado (o padrão). Os cabeços, o sumário de navegação e as linhas do sumário geradas a partir de um título guardam só o texto, assim como o texto de um :chip[…].
• Links no estilo de referência ([text][id]) e autolinks (<https://…>) não são reconhecidos (veja O que NÃO é suportado).

Na VDT o destino fica em cada segmento com link, como VDTLineSegment.href. O parser guarda os links de um trecho como intervalos do seu texto, em InlineSpan.links, e nunca divide um trecho por causa de um link; por isso um link não pode mudar o layout.

#Chips em linha

:chip[text] compõe text dentro de uma caixa (um “chip” arredondado e colorido) que flui com a linha: as palavras de um banco de palavras ou de um exercício de classificação, teclas do teclado, etiquetas. :chip[text]{style="key"} escolhe um estilo nomeado de chipStyles (veja a referência de configuração); sem style, ou com um id que nenhum estilo declara, o chip usa o primeiro estilo (um estilo chip embutido quando a configuração não tem nenhum; o Sandbox avisa quando o id é desconhecido).

Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy.

• Uma unidade. Um chip nunca é quebrado nem hifenizado por dentro; a linha quebra entre os chips, nos espaços entre palavras em volta deles. Um chip mais largo que a linha inteira transborda dela em vez de se dividir.
• Largura. O avanço do chip é o texto mais o preenchimento horizontal e o contorno dos dois lados. A justificação estica só os espaços entre palavras, nunca o interior de um chip. O gap do estilo é o espaço mínimo mantido entre a caixa e uma palavra ou chip vizinho do outro lado de um espaço; um espaço mais estreito é completado (exceto na borda de uma linha e junto a uma pontuação colada, como em :chip[a],).
• Altura. A caixa é uma faixa em volta da linha de base, 0,8 em acima e 0,25 em abaixo no tamanho do chip, acrescida do preenchimento vertical e do contorno. O preenchimento vertical é pintado fora da caixa da linha e nunca altera a entrelinha, de modo que a grade de linhas de base se mantém; uma caixa mais alta que o passo de linha pode encostar num chip da linha de cima ou de baixo, e o Sandbox sinaliza dois chips em linhas diferentes que se sobrepõem (“Chips encostam na linha vizinha”) para que se possa reduzir o preenchimento, o contorno ou o tamanho.
• Texto. O texto do chip aceita marcas em linha próprias (:chip[**bold** word], :chip[x^2^]) e a ênfase em volta (**:chip[a]**); o estilo pode definir família, tamanho, cor, negrito e itálico. Escreva \] para um colchete literal dentro dele. Referências, amostras de cor e fórmulas dentro de um chip ficam literais, e \$ imprime um cifrão (até o postext 1.4 imprimia também a barra invertida).
• Vazio. Um chip só de espaços (:chip[ ], espaços inseparáveis incluídos) é uma caixa vazia (uma lacuna para resposta, um sinal de fim): tão larga quanto o preenchimento horizontal e o contorno do seu estilo, tão alta quanto um chip com palavras. Dimensione a lacuna com o paddingX de um estilo (:chip[ ]{style="blank"}). Sem nada entre os colchetes, :chip[] continua texto literal.
• Onde. Parágrafos, itens de lista, citações em bloco, boxes, células de tabela, legendas e notas. Os títulos mantêm :chip[…] como texto literal.
• Saída. Canvas, HTML e PDF pintam a caixa e compõem as palavras como texto real: selecionável no HTML, extraível e na ordem de leitura no PDF (num PDF com tags, a caixa é um artefato de layout e as palavras pertencem ao parágrafo).

#Versaletes

:smallcaps[text] compõe text em versaletes: os nomes das personagens numa peça de teatro, uma sigla no texto corrido, as primeiras palavras de um capítulo. As letras minúsculas são compostas como maiúsculas a 70% do tamanho do texto, enquanto maiúsculas, dígitos e pontuação mantêm o tamanho cheio, de modo que :smallcaps[Hamlet] imprime um H de tamanho cheio seguido de AMLET em versaletes.

Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading.
 
The :smallcaps[unesco] report and the :smallcaps[who] guidelines.

• Sintetizados. Os versaletes são desenhados a partir das próprias maiúsculas da fonte, do mesmo jeito no canvas, no HTML e no PDF, de modo que o texto mede e quebra de forma idêntica em todos eles. Os versaletes reais de uma fonte (o recurso OpenType smcp) não são usados; para eles, componha o texto numa família de versaletes (uma família cujo nome termina em “SC”, por exemplo) por meio de um estilo de parágrafo.
• Marcas. O texto aceita marcas em linha próprias (:smallcaps[**Ophelia**]) e a ênfase em volta (*:smallcaps[Act I]*); escreva \] para um colchete literal dentro dele. Uma referência ou um chip dentro dele também sai em versaletes, e uma referência continua sendo um único link no HTML e no PDF; uma fórmula, não.
• Quebra. As palavras quebram e são hifenizadas normalmente; a hifenização lê cada palavra na sua própria caixa (maiúscula ou minúscula).
• Onde. Parágrafos, itens de lista, citações em bloco, boxes, células de tabela, legendas e notas, e títulos enquanto headings.inlineMarks estiver ativado (o padrão); com ele desativado, a marcação é removida do título e o texto sai como foi escrito.
• Parágrafos inteiros. Um estilo de parágrafo ou o corpo de um boxe com smallCaps: true compõe todo o seu texto assim (veja Estilos de parágrafo).
• Texto. O canvas, o HTML e o PDF guardam as letras como foram pintadas: copiar :smallcaps[Hamlet] dá “HAMLET”.

#Orientação no texto vertical

No texto vertical (layout.writingMode: 'vertical-rl') os caracteres chineses ficam em pé, palavras latinas e números longos são girados de lado, e um número de no máximo dois dígitos fica em pé numa única célula, a menos que esteja numa frase latina, cujas palavras ele acompanha (veja Configuração › Números no texto vertical). Três marcas destacam um trecho manualmente:

第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。

• :tcy[…] (tate-chu-yoko, 縱中橫) compõe o texto lado a lado numa única célula em pé de um em, comprimido na horizontal quando é mais largo: :tcy[120], :tcy[3.0], :tcy[A+]. Até uns quatro caracteres ficam legíveis.
• :upright[…] põe cada caractere em pé numa célula própria, com as letras latinas centralizadas nela: uma sigla lida letra a letra coluna abaixo. A linha nunca quebra dentro dela.
• :sideways[…] gira o trecho inteiro com a linha, caracteres chineses inclusive: um número de dois dígitos que o autor quer deitado.
• O texto continua no texto simples; as marcas aceitam outras marcas em linha dentro delas (:tcy[**12**]), um link (:sideways[[iPhone](https://…)]) e umas às outras, prevalecendo a mais interna (:tcy[:upright[AB]] põe A e B em pé), e escreva \] para um colchete literal. No texto horizontal elas não mudam nada.
• Uma referência, um marcador de nota, uma fórmula, um chip ou uma amostra de cor dentro de uma marca mantém sua própria composição: :sideways[iPhone[^1]] gira iPhone e deixa o número da nota como todo número de nota é composto; o número de uma referência fica em pé numa célula por cjk.uprightDigits, como qualquer número curto.
• Um elemento de texto de design com inlineMarks: true também as aceita quando é composto na vertical (veja Configuração › Elementos de texto vertical).
• Para a quebra e a justificação, uma célula :tcy e cada caractere de :upright contam como caracteres chineses, e nenhum espaço han–latino é inserido ao lado deles.

#Marcas chinesas, rubi e warichu

As edições chinesas e japonesas marcam o texto entre as linhas em vez de usar itálico ou sublinhado, anotam os caracteres com suas leituras e compõem comentários dentro da linha. Sete diretivas fazem isso. Diagramação em chinês e Diagramação em japonês explicam as convenções por trás delas. Elas preservam o texto: os caracteres entre os colchetes ficam no parágrafo (a busca, o sumário, as âncoras do índice e o texto copiado os leem como foram escritos), e as diretivas aceitam as outras marcas em linha dentro e em volta delas, inclusive as aninhadas. Escreva \] para um colchete literal.

此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。
 
{滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。
 
寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：……
 
{東京|とう|きょう}の:ruby[紫陽花]{rt="あじさい"}は*とんと*:sideline[見事]だ。:book[こころ]を読む。
 
:kunten[學]{okuri="ビテ"}而:kunten[時]{okuri="ニ"}:kunten[習]{kaeri="二" okuri="フ"}:kunten[之]{kaeri="一" okuri="ヲ"}。

• :dots[text] põe um ponto de ênfase (着重号) sob cada caractere no texto horizontal, à direita dele no texto vertical, e nenhum na pontuação nem nos espaços. style="dot|circle|sesame" (padrão dot), fill="open" para um contorno, pos="over|under" para o outro lado. A ênfase Markdown *…* sobre caracteres chineses ou japoneses faz o mesmo com cjk.emphasis: 'dots', o padrão num documento chinês ou japonês; letras latinas na mesma ênfase continuam em itálico. Os atributos omitidos vêm de cjk.emphasisMark: um ponto sob o texto em chinês, um gergelim sobre ele (à direita, no texto vertical) em japonês.
• :name[text] traça a linha de nome próprio (专名号) sob o texto (à esquerda dele no texto vertical), e :book[text] a marca de título de obra (书名号): 《》 em volta do título (〈〉 para um título dentro de outro), a linha ondulada das edições clássicas e de Taiwan, ou nada, conforme cjk.bookTitleMark (por padrão, colchetes na China continental e no Japão, a linha ondulada em Taiwan e Hong Kong). Num documento japonês os colchetes são 『』, e 「」 para um título dentro de outro (cjk.bookTitleBrackets). Uma única fonte serve a uma edição moderna do continente e a uma clássica. Dois nomes ou títulos lado a lado mantêm suas linhas separadas.
• :ruby[base]{rt="…"} compõe leituras sobre a base (pinyin), ou à direita de cada caractere (zhuyin, o padrão para leituras em bopomofo). Com tantas leituras quanto caracteres, separadas por espaços ou |, cada caractere recebe a sua e a linha pode quebrar entre eles (rubi mono); group, ou uma contagem que não bate, compõe uma única leitura centralizada sobre a base inteira, que nunca quebra. pos="over|under|right" escolhe o lado. A forma compacta {紅樓|hóng|lóu} (uma leitura por |) ou {紅樓|hónglóu} (uma leitura para a base inteira) tem o mesmo efeito, mas só quando a base contém um caractere han, kana ou bopomofo, fora de fórmulas, código e atributos, de modo que {x|x>0} na prosa latina continua texto. Uma barra invertida antes da chave ou da barra vertical mantém uma forma chinesa como texto: \{紅|hóng} e {紅\|hóng} imprimem {紅|hóng}. Uma base que abre ou fecha uma linha se alinha a essa borda junto com sua leitura. mode=mono|group|jukugo escolhe como as leituras se distribuem sobre a base (mode=group equivale a group), e align=center|jis|start como se espaça uma leitura mais curta que sua base. Num documento japonês, a forma por caractere de uma palavra de dois ou mais caracteres ({東京|とう|きょう}, rt="とう|きょう") é rubi jukugo: cada caractere mantém sua leitura, que pode avançar sobre o caractere seguinte da palavra, a linha pode quebrar entre eles, e as leituras são espaçadas e avançam sobre kana conforme cjk.ruby.align e cjk.ruby.overhang; uma leitura para a base inteira ({紫陽花|あじさい}, o 《》 do Aozora) é rubi de grupo; mode=mono mantém uma leitura por caractere sem avançar sobre os vizinhos.
• :sideline[text] traça uma linha lateral (傍線) ao lado do texto, pontuação e espaços incluídos: embaixo dele no texto horizontal e à direita no texto vertical. style="solid|double|wavy|dotted" (padrão solid), pos="over|under" (no texto vertical, over é a direita e under a esquerda; position= também funciona). Funciona em qualquer escrita, inclusive numa frase em inglês sublinhada.
• :warichu[note] compõe uma nota (双行夹注) em duas linhas com metade do tamanho do texto dentro da linha, lendo-se primeiro a linha de cima (a da direita no texto vertical). Uma nota longa preenche o que resta da linha e continua na linha, coluna ou página seguinte. open e close a envolvem em colchetes no tamanho do texto; cjk.warichu define o tamanho, a cor e os colchetes padrão (（） num documento japonês). Uma nota em escrita latina quebra entre as palavras.
• :kunten[字]{kaeri="…" okuri="…" tate} compõe as marcas de kanbun do último caractere entre os colchetes: kaeri a marca de retorno (レ, 一 二 三, 上 中 下, 甲 乙 丙, 天 地 人, e 一レ 上レ 甲レ 天レ; os code points ㆑ ㆒ … funcionam igual), okuri o okurigana (os parênteses do Aozora, （ヲ）, são descartados), e a flag tate o tatesen que o liga ao caractere seguinte. O texto não é reordenado: as marcas são compostas em meio corpo ao lado dele (cjk.kunten), e o texto copiado fica 學ビテ而時ニ習フ之ヲ, com o okurigana e sem as marcas de retorno. Um rubi dentro funciona para os caracteres lidos duas vezes: :kunten[:ruby[未]{rt="ザル" pos=under}]{kaeri="レ" okuri="ダ"}.

O passo de linha nunca muda: marcas e leituras ficam no espaço da entrelinha, e a composição avisa quando o espaço entre as linhas de um parágrafo é estreito demais para elas (cjkMarksExceedLeading, rubyExceedsLeading, kuntenExceedsLeading), e quando as marcas sob uma linha e as leituras sobre a seguinte não cabem no espaço que dividem, num mesmo parágrafo ou entre dois. Dê aos parágrafos anotados um estilo de parágrafo com mais entrelinha. Marcas, leituras e notas são desenhadas em parágrafos, títulos, itens de lista, citações em bloco e boxes, e também em legendas, células de tabela e notas, cuja entrelinha é verificada do mesmo modo; em cabeços e designs o texto sai sem elas. Com cjk.bookTitleMark: 'brackets', os 《》 de um título são pontuação do texto: legendas, células, notas, linhas do sumário, marcadores e entradas de índice os mantêm. Veja Configuração › Marcas, rubi e warichu.

#Direção do texto na marcação

Um documento corre na direção que seu locale implica (direction na configuração: da direita para a esquerda em árabe, persa, urdu ou hebraico). Dentro dele, a marcação define a direção de um bloco ou de um trecho de texto, para uma citação em inglês num livro em árabe ou uma em árabe num livro em inglês.

• Um título ou um contêiner: {dir=ltr} ou {dir=rtl} nos seus atributos, # Introduction {dir=ltr}, :::paragraphs{dir=ltr}, :::callout{dir=rtl}. Todo bloco dentro de um contêiner assume essa direção, até um contêiner aninhado ou um título que defina outra. Um parágrafo simples, uma lista ou uma citação não têm atributos próprios: envolva-os em :::paragraphs{dir=…}. Outros valores são ignorados. O lang de um contêiner (:::paragraphs{dir=ltr lang=en}) indica do mesmo modo o idioma dos blocos dentro dele: suas listas numeradas usam os algarismos desse idioma.
• Um trecho de texto: :ltr[…] e :rtl[…] isolam seu texto (os LRI…PDI e RLI…PDI do algoritmo bidirecional do Unicode): ele é ordenado por dentro, e o parágrafo em volta o vê como um único caractere neutro. {lang=…} marca o idioma do trecho no HTML e no PDF. Um marcador de nota, um :ref ou uma fórmula dentro dele fazem parte do isolamento, e os isolamentos podem se aninhar.

:::paragraphs{dir=ltr}
The opening of the *Nights* in Lane's translation.
:::
 
ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩.

Um bloco composto contra a direção do documento mantém seu próprio lado de início: o recuo, os marcadores de lista e o final alinhado da última linha passam para o lado em que o texto começa. Use um isolamento quando um título latino terminar num caractere neutro (um ponto final, um parêntese) que, sem isso, se juntaria ao árabe em volta. Os próprios caracteres de controle do Unicode (U+2066–2069, U+202A–202E, U+200E, U+200F, U+061C) também são respeitados. No editor do Sandbox, cada linha corre na direção da sua primeira letra. Veja Diagramação em árabe.

#Notas de rodapé

Uma nota de rodapé tem duas partes: o marcador [^id] onde a nota é citada, e a definição, um parágrafo próprio que começa com [^id]: em qualquer ponto do capítulo.

The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.
 
[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.

• Marcador. [^id] imprime o número da nota como sobrescrito, colado à palavra anterior (escreva-o depois da pontuação, como acima). O id aceita letras, dígitos, -, _, . e :. O marcador funciona em parágrafos, itens de lista, citações em bloco e boxes; em títulos, legendas e células de tabela ele sai como foi escrito.
• Definição. Um parágrafo que começa com [^id]:; seu texto vai até a próxima linha em branco e aceita as marcas em linha habituais (negrito, itálico, links, :ref, fórmulas, chips). As definições saem do fluxo onde quer que estejam escritas, de modo que podem ficar sob o parágrafo que as cita ou todas juntas no fim do capítulo. Vale a primeira definição de cada id.
• Números. As notas são numeradas na ordem em que são citadas pela primeira vez, recomeçando a cada capítulo (um título de nível 1, e cada documento de um livro); uma nota citada duas vezes mantém seu primeiro número e é composta uma só vez. footnotes.numbering: 'document' mantém a numeração corrida pelo livro todo, e 'page' a recomeça a cada página, como fazem os livros chineses; footnotes.numberFormat: 'circled-decimal' escreve ① ② ③ na linha de base. footnotes.numberFormat: 'symbols' as marca com *, †, ‡, §, ‖, ¶, depois dobrados, recomeçando a cada página, como fazem as revistas científicas.
• Texto japonês. Escreva o marcador antes de um 。 de fim de frase (先生[^1]。): ele fica com o caractere anterior, e o 。 nunca abre uma linha. Um livro japonês vertical compõe seus marcadores （1） à direita da linha e suas notas depois do capítulo, por padrão; footnotes.markerPosition: 'side' compõe um marcador pequeno ao lado da palavra, sem ocupar espaço na linha, e footnotes.placement: 'spread' compõe as notas ao lado do texto de cada página dupla (veja Configuração › Notas de rodapé).
• Onde a nota vai. Por padrão, no pé da coluna que contém a linha que a cita, sob um fio curto: a linha e sua nota sempre ficam na mesma coluna, e uma linha cuja nota não cabe segue adiante junto com ela. Num layout de uma coluna, isso é o pé da página. footnotes.placement: 'chapterEnd' compõe todas as notas de um capítulo depois do seu último bloco, por padrão no pé da coluna que elas fecham. Veja Notas de rodapé na referência de configuração para os tamanhos, o fio e o espaçamento.
• Verificações. Um marcador sem definição (undefinedFootnote) imprime seu número sobre uma nota vazia; uma definição que nenhum marcador cita (unusedFootnote) não é composta. O Sandbox lista os dois casos no painel Verificações.

#Referências cruzadas e âncoras

Uma referência cruzada nomeia um lugar do livro e imprime seu número, seu título ou sua página: veja a seção 3.2, como explica o capítulo 4, na p. 112. As palavras e os números acompanham o texto, de modo que mover uma seção, renumerar os capítulos ou recompor o livro atualiza todas as referências. No PDF, no HTML e nas visualizações do Sandbox, cada referência é um link: um clique leva o leitor ao destino, inclusive em outro capítulo.

Âncoras. Uma referência precisa de algo para onde apontar:

• Um título com um identificador: ## Method {#sec-method} (a forma do Pandoc; id="sec-method" também funciona).
• Um boxe ou outro contêiner aberto com um: :::callout{#box-safety title="Safety"}. Um boxe de um estilo numerado (um teorema) é referido pelo rótulo e pelo número: Teorema 2.
• Uma fórmula destacada com um \label{eq:x} (veja Fórmulas matemáticas): uma referência imprime o número como a fórmula o imprime, (3).
• Um ponto do texto: :anchor{#key-idea} insere uma âncora invisível; [the key idea]{#key-idea} mantém suas palavras e lhes dá um nome.

Um identificador aceita letras, dígitos, -, _, . e :. Ele precisa ser único no livro: o painel Verificações lista um identificador definido duas vezes (duplicateAnchor), e as referências levam à sua primeira definição.

Referências. :ref{id="…"} aponta para uma âncora do mesmo modo que aponta para uma figura ou uma tabela:

## Method {#sec-method}
 
The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.

\eqref{x} e \ref{x} do LaTeX também funcionam no texto: \eqref como uma referência sem estilo, \ref como style=number, de modo que \ref{thm:main} imprime 2 e \ref{fig:map} o número de uma figura. Um ~ logo antes de um deles é um espaço inseparável (Theorem~\ref{thm:main}). Dentro de $…$ eles pertencem à fórmula.

text="…" imprime as suas próprias palavras e continua sendo um link; case=capitalize começa o rótulo com maiúscula (Seção 3.2 no início de uma frase). As palavras seguem o idioma do documento (sección 3.2, 第3.2节, S. 112) e podem ser alteradas em Referências cruzadas na configuração; um número de título que o modelo do título já escreve por extenso (Capítulo 4, 第四章) sai como está.

Referências de página só são conhecidas depois que o livro é diagramado. O motor diagrama o documento de novo com as páginas da passada anterior até que elas se estabilizem, como faz com o sumário; até lá, uma página sai como ?.

pandoc-crossref. Um texto escrito para o pandoc-crossref funciona igual: @sec:method, [@fig:map], e [-@tbl:data] para só o número. O prefixo (sec, fig, tbl, eq, lst) pode fazer parte do identificador ({#sec:method}) ou ficar fora dele ({#method}). Um @ colado a uma palavra, como num endereço de e-mail, continua texto.

Uma referência a um id que nada define imprime ? e o painel Verificações a lista (unknownResourceId). No editor do Sandbox, @ oferece as figuras, as tabelas, os títulos com id e as âncoras do livro.

#Citações e bibliografia

Escreva as citações como o Pandoc as lê, mantenha as referências no documento e escolha o estilo de citação nas configurações: passar de APA para IEEE, ou para notas Chicago, muda a configuração de estilo, não o texto. Toda citação tem um link para sua entrada na bibliografia.

#Como citar

As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.

• [@key] cita entre parênteses; várias obras vão num mesmo par de colchetes, separadas por ;.
• Localizador: depois de uma vírgula, p. 33, pp. 4–6, chap. 2, sec. IV, fig. 3, vol. 2, n. 12, l. 4, § 4.2; um número sozinho é uma página. As palavras em espanhol (pág., cap.) e em chinês (页, 章) também funcionam.
• Prefixo e sufixo: texto antes do @ (see) e depois da chave ou do localizador (, emphasis added). O sufixo mantém a vírgula escrita antes dele, com ou sem localizador: [@brown2020, inter alia] imprime (Brown et al., 2020, inter alia), como faz o Pandoc; escrito sem vírgula ([@brown2020 inter alia]), sai sem ela. A ênfase num prefixo ou num sufixo é composta como ênfase em todos os estilos: [*e.g.*, @brown2020, *inter alia*].
• [-@key] omite o autor, para uma frase que já o nomeia.
• @key cita dentro da frase (García (2020)); @key [p. 4] acrescenta um localizador.
• Em legendas: a legenda de uma figura ou de uma tabela, e sua nota, citam como o texto (Prior best from [@cobbe2021].). As obras citadas ali entram na bibliografia sem nocite, e um estilo numerado as numera onde o recurso é posicionado: depois das citações do parágrafo que se refere a ele pela primeira vez (seu bloco ::resource ou seu primeiro :ref). Uma citação numa célula de tabela continua texto.
• Um @ colado a uma letra ou a um dígito (um endereço de e-mail), um @ em código em linha e \@ são texto. Uma citação para a qual o livro não tem referência sai como foi escrita, de modo que um documento sem referências fica como antes. Numa citação de várias obras, uma chave que nenhuma referência define sai em negrito depois das outras ((Glen, 1955) **@nye1953**), para que a obra faltante apareça na página além de nos avisos. Dois-pontos depois de uma citação são texto: [@french2018]: the land….
• Em texto chinês, japonês e coreano, uma citação segue o último caractere sem espaço (周明远@zhou2019认为), e uma citação autor-data assume os sinais de largura total do texto em volta: （施雅风等，1988；刘时银等，2015）.

#Referências

As referências são escritas no documento, em formato CSL (o modelo de dados do Zotero e do Pandoc):

---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---

ou num bloco :::references, em BibTeX (uma exportação do Zotero, do JabRef ou do Google Acadêmico), CSL-JSON ou CSL-YAML:

:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::

O bloco não imprime nada. nocite lista obras sem citá-las (@*: todas). Num livro, as referências escritas em qualquer capítulo valem para o livro inteiro.

Numa lista de nomes BibTeX, and others representa os nomes omitidos (author = {Tan, Wei and others}): todos os estilos imprimem et al. no lugar deles. Em YAML, escreva others como último nome da lista.

#A bibliografia

:::bibliography compõe a lista de obras citadas onde estiver; sem ele, a lista vem depois do último capítulo, com um título no idioma do documento (References, Referencias, 参考文献). :::bibliography{title="Works cited"} muda o título e title="" o omite; scope=chapter lista as obras que o capítulo cita (uma coletânea). Cada entrada é uma âncora (ref-<key>), de modo que um link Markdown para #ref-garcia2020 chega a ela, e o PDF a marca como BibEntry.

scope=new lista as obras citadas até ali no documento que nenhuma lista anterior imprimiu, na ordem do estilo e com seus números: um :::bibliography{scope=new} depois do texto principal e outro depois dos Métodos dão as duas listas de um artigo da Nature, a segunda com a numeração seguindo a da primeira. Um estilo numerado conta suas citações ao longo do livro; com citations.numbering: 'chapter', cada capítulo (cada documento, e cada título de nível 1 depois de uma citação) numera as suas a partir de 1, e a lista do capítulo usa esses números, como fazem os relatórios de um boletim ou os artigos de anais.

#Estilos

O estilo decide o que dizem uma citação e uma entrada. Os estilos incluídos estão listados abaixo; qualquer outro estilo CSL (há mais de dez mil no repositório de estilos do Zotero) pode ser carregado a partir do seu arquivo .csl em Configurações → Citações.

Com um estilo de notas, cada citação vira uma nota de rodapé, posicionada e numerada conforme as configurações de notas de rodapé; as citações seguintes da mesma obra usam uma forma abreviada. Em texto chinês, citations.notes: 'warichu' as compõe como notas de duas linhas dentro da linha (夹注); uma nota seguida de um sinal chinês (，, 。) dispensa seu próprio ponto final.

Chinês. Os estilos GB/T 7714-2015 escrevem os códigos de tipo de documento ([M], [J], [D], [EB/OL]), mantêm os nomes chineses inteiros e escrevem 等 depois de três autores de uma obra chinesa e et al. depois dos de uma obra ocidental, escolhendo pelo language de cada obra. No texto vertical, um número sobrescrito fica à direita do seu caractere; citations.marker: 'corner' escreve 〔1〕, que fica em pé.

Motor. As citações são formatadas pelo pacote postext-citeproc (citeproc-js e os estilos CSL). O Sandbox o carrega para os documentos que têm citações; no seu próprio código, registre-o antes da diagramação:

import 'postext-citeproc/register';

O painel Verificações lista uma chave que nenhuma referência define (unknownCitationKey) e um bloco de referências que não pode ser lido (referencesUnreadable).

#Índice remissivo

Um índice remissivo lista os termos de um livro com as páginas em que aparecem. Marque cada termo onde o texto trata dele e imprima o índice com :::index onde ele deve ficar, normalmente num capítulo próprio no fim. O motor descobre a página de cada marca depois da diagramação, de modo que os números acompanham o texto: acrescente um parágrafo, mova um capítulo ou mude o formato, e o índice imprime as páginas novas.

Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}
 
# Index {style="index"}
 
:::index

#Marcas de índice

• :index[text] imprime text e o registra pelas suas próprias palavras. As marcas em linha dentro dele são impressas e descartadas da entrada. Atributos depois do colchete o registram em outro lugar: :index[iron deficiency]{term="Anaemia!iron-deficiency"}.
• :index{term="…"} não imprime nada. A marca assume a página da palavra escrita logo antes dela na sua linha ou, quando abre uma linha, a da palavra seguinte. Uma linha que só contém marcas é removida, de modo que uma marca numa linha própria nunca divide um parágrafo nem acrescenta espaço.
• Onde. Parágrafos, títulos, itens de lista, citações em bloco, boxes e definições de notas de rodapé. Em legendas, células de tabela e elementos de design, uma marca sai como foi escrita. Dentro de código em linha, e depois de uma barra invertida (\:index), ela é texto.

Uma marca sem termo (:index{} ou :index{see="…"} sozinho) não indexa nada e gera indexMarkInvalid.

#Como imprimir o índice

:::index imprime o índice principal onde estiver, e :::index{index="names"} um índice nomeado. A diretiva se expande em blocos comuns, um por entrada, que fluem por colunas e páginas como texto: sob um título cujo estilo de título define um layout de duas colunas, ela gera o índice de duas colunas habitual. Um clique numa entrada leva à linha da diretiva.

# Index of names {style="index"}
 
:::index{index="names"}
 
# Index of subjects {style="index"}
 
:::index

• Ordem. As entradas seguem a ordem alfabética do idioma do documento (locale, ou index.locale): uma letra acentuada fica com sua letra-base (Árbol em A), e em espanhol ñ vem depois de n, sob um cabeçalho próprio. As entradas que começam por um símbolo vêm primeiro, depois as que começam por um dígito, depois as letras. As subentradas se ordenam do mesmo modo sob sua entrada, recuadas um passo por nível. Um índice japonês ordena pela leitura na ordem da JIS X 4061 e agrupa por série do gojūon (あ行, か行…), com as entradas latinas antes das em kana (veja Diagramação em japonês › Índice na ordem do gojūon).
• Grupos. Cada nova letra inicial abre um grupo: um cabeçalho de letra (index.groups) e uma linha de espaço acima dele (nenhuma acima do primeiro grupo). O cabeçalho é composto num mesmo bloco com a primeira entrada do grupo, de modo que nunca fica sozinho no fim de uma coluna; uma entrada sem página própria (que só encabeça suas subentradas) é composta com sua primeira subentrada pelo mesmo motivo.
• Números de página. Os rótulos que as páginas imprimem, inclusive os romanos dos elementos pré-textuais. As páginas de uma entrada são ordenadas e cada uma aparece uma vez; páginas consecutivas se juntam num intervalo (12–14, index.mergeRanges), uma página que cai dentro de um intervalo da mesma entrada é absorvida por ele (uma página principal ali deixa o intervalo em negrito), e index.rangeFormat: 'chicago' abrevia o segundo número (234–37). As páginas em negrito (principais) ficam separadas. No PDF, cada número tem um link para sua página.
• Remissões fecham a entrada: Termo. See Destino quando a entrada não tem páginas, Termo, 12. See also Destino quando tem. Os rótulos seguem o idioma do documento (See, Véase…) e podem ser definidos em index.see.
• Livros. Num livro diagramado capítulo a capítulo (o Sandbox, buildBundle), o capítulo que imprime o índice recebe as marcas de todos os capítulos com suas páginas, e só é diagramado de novo quando uma delas muda de lugar. Um documento que contém tanto as marcas quanto o índice é diagramado de novo até que os números se estabilizem, como acontece com :::toc.

Veja Índice remissivo na referência de configuração para a tipografia, os recuos e os separadores.

#Fórmulas matemáticas

O suporte a fórmulas matemáticas é parte integral do formato do documento. O Postext lê $…$ para fórmulas em linha e $$…$$ para fórmulas destacadas (em bloco), e as renderiza com o MathJax no modo SVG. Os mesmos contornos vetoriais alimentam os três renderizadores, de modo que a visualização no canvas, a exportação HTML e a saída PDF coincidem pixel a pixel, e o PDF continua totalmente vetorial em qualquer nível de zoom.

• Em linha: $…$. Reconhecida dentro de qualquer bloco de texto (parágrafo, título, citação em bloco, item de lista). Entra na linha como uma única caixa atômica e inquebrável; o Knuth-Plass a trata como uma palavra que não pode ser dividida. Se a altura natural da fórmula romper a caixa da linha, ela é reduzida por igual para preservar a grade de linhas de base; expressões muito altas pedem o modo destacado.
• Destacada: $$…$$. Numa linha própria ($$\int_0^1 x^2\,dx$$) ou em várias linhas, delimitada por marcadores $$ em linhas próprias. É renderizada centralizada na coluna e encaixada na grade de linhas de base, com margens superior e inferior configuráveis (math.marginTop, math.marginBottom): exatamente o mesmo mecanismo de correção que os títulos usam, de modo que o parágrafo depois da fórmula volta para a grade.
• Texto em volta de uma fórmula destacada: uma fórmula destacada numa linha própria interrompe um parágrafo mesmo sem linha em branco acima dela. O texto anterior é um parágrafo que a introduz; o texto escrito logo abaixo do $$ de fechamento, sem linha em branco, continua o parágrafo interrompido e é composto sem recuo de primeira linha, como o TeX compõe o “onde …” depois de uma fórmula destacada. Uma fórmula separada do texto acima por uma linha em branco (ou que vem depois de uma lista, de uma citação ou de um título) não interrompe nada: o texto depois dela é um parágrafo novo, recuado como de costume, com ou sem linha em branco (math.indentAfterDisplay: false o compõe sem recuo também). Só uma fórmula destacada inteira interrompe um parágrafo: uma fórmula sozinha na linha, ou um bloco $$ fechado antes da próxima linha em branco; uma linha como $$a$$ and $$b$$ continua texto. math.keepWithLeadIn mantém a fórmula na coluna da linha que a introduz. (Até o postext 1.4, uma linha $$…$$ sem linha em branco acima era lida como parte do parágrafo e impressa como foi escrita.)
• Números de equação: \label{eq:x} numa fórmula destacada a numera, na ordem de leitura: (1), (2)… Uma fórmula com número ocupa a coluna (ou a largura interna do boxe), com a equação centralizada e o número alinhado à direita na mesma linha. Num align, gather, alignat, flalign ou eqnarray, cada linha que tem um \label recebe seu próprio número, a menos que a linha diga \nonumber ou \notag. Uma fórmula sem \label não é numerada, como $$…$$ nunca foi. \tag{…} continua numerando uma fórmula com o texto que você der (\tag*{…} sem os parênteses) e não entra na contagem; um \label ao lado dá nome a esse texto. O formato, os números de capítulo ou de seção (2.3) e os recomeços se definem em math.equationNumbering. Ponha o \label no nível superior da fórmula ou da linha: não dentro de aligned, split ou cases.
• Referências a equações: \eqref{eq:x} no texto imprime o número como a fórmula o imprime, (3), e \ref{eq:x} só o número, 3; ambos são links, como toda referência cruzada. Eq.~\eqref{eq:x} mantém o ~ como faz o LaTeX: um espaço inseparável. :ref{id="eq:x"} e @eq:x também imprimem (3). Dentro de uma fórmula, \eqref e \ref imprimem o número (sem link). Um rótulo que nada define imprime ? e aparece no painel Verificações.
• Escape: \$ é um cifrão literal. Delimitadores $ ou $$ sem par geram uma entrada unclosedMath no painel Verificações do Sandbox, com uma âncora para a origem que leva até ela com um clique.
• Legendas, notas e células de tabela também compõem fórmulas em linha (desde o postext 1.19), na linha junto com o texto e com o alinhamento da célula, no tamanho do trecho. Ali um $ só abre fórmula pela regra do Pandoc: nenhum espaço depois do $ de abertura, nenhum espaço antes do de fechamento e nenhum dígito logo depois dele, de modo que os preços de $5 to $10 continuam texto; \$ imprime um cifrão, de modo que uma mesma string com escape é lida igual no texto e numa tabela. O rótulo de um chip não aceita fórmulas. Até o postext 1.18, um $ ali sempre saía como foi escrito.
• Erros: um código TeX que o MathJax rejeita (macros indefinidas, erros de sintaxe) aparece como um aviso invalidMath. A fórmula é substituída por um pequeno marcador vermelho para que a geometria do layout continue válida.
• Configuração: a seção math da configuração expõe enabled, fontSizeScale (relativo ao tamanho do texto em volta: em 1.0, um em da fórmula tem esse tamanho, o do corpo para fórmulas destacadas e para fórmulas em linha no texto corrido; desde o postext 1.5, que compõe as fórmulas cerca de 13% menores que o 1.4, enquanto os pacotes e os livros do Sandbox salvos pelo 1.4 mantêm seu tamanho; veja Tamanho das fórmulas), color (herda a cor do corpo quando não definido) e as margens das fórmulas destacadas.
• O motor: o MathJax é carregado sob demanda. O Sandbox e o worker de layout o iniciam por conta própria; no seu próprio código, chame await initMathEngine() antes de buildDocument, ou cada fórmula será diagramada como uma caixa cinza de marcação (veja Como iniciar o motor de fórmulas).

The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants.
 
$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

Uma fórmula no meio de uma frase, e a frase continuando depois dela sem recuo:

For a pendulum of length $L$ the period is
$$T_0 = 2\pi\sqrt{L/g}$$
where $g$ is the acceleration of free fall.

Equações numeradas e as referências a elas:

The energy is conserved,
$$
\begin{align}
E &= T + V \label{eq:energy} \\
  &= \tfrac12 m v^2 + m g h \nonumber
\end{align}
$$
and Eq.~\eqref{eq:energy} holds at every instant.

Teoremas, lemas e demonstrações. Um estilo de boxe com numbering conta seus boxes, como o amsthm do LaTeX conta os ambientes de teorema: cada boxe abre com o rótulo e o número em negrito, “Teorema 2.”, com o title do bloco depois do número entre parênteses, “Teorema 2 (Bradley–Terry).”, e uma referência ao seu {#id} imprime “Teorema 2” (\ref{thm:x} ou style=number, só o 2). Os estilos que indicam o mesmo contador o compartilham, de modo que um lema depois de um teorema é o Lema 3. O endMark de um estilo de demonstração encerra seus boxes com ∎ ou □, alinhado à direita na última linha. Veja Enunciados numerados e demonstrações para os estilos.

:::callout{type="theorem" #thm:main title="Bradley–Terry"}
Every reward class holds one reparameterised reward.
:::
 
:::callout{type="proof"}
Apply the projection of \eqref{eq:projection} to any member of the class.
:::
 
By :ref{id="thm:main"}, the objective is unchanged.

#Recursos

Imagens, SVGs, tabelas e vídeos não são escritos no meio do texto. Eles são declarados uma vez como recursos (gerenciados no painel Recursos do Sandbox, que cuida do envio de imagens e SVGs, de um editor de tabelas interativo, de vídeos do YouTube, do Vimeo e enviados, e da edição de legendas e posicionamento) e depois ligados à sua prosa por id. Referenciar um recurso basta para incorporá-lo: você o menciona uma vez com um :ref{id="…"} em linha, e o motor faz a figura ou a tabela flutuar até o primeiro espaço livre depois dessa referência (o pé da coluna em que você o menciona, o topo da coluna seguinte, uma faixa da página seguinte), como faria um compositor de livros impressos. Você não o posiciona uma segunda vez.

As duas formas abaixo são sintaxe nova que não colide com o CommonMark, de modo que um documento que as usa continua legível como texto simples em qualquer outro visualizador de Markdown.

#Referência em linha (a forma principal)

Refira-se a um recurso de dentro da prosa com :ref{id="…"}. A primeira referência ao mesmo tempo incorpora o recurso (para que ele seja posicionado na página) e renderiza o número calculado, precedido por padrão do rótulo curto do tipo:

As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.

é renderizado como: As shown in Fig. 1.7, the lantern room sits above the gallery. E o próprio diagrama flutua até o espaço livre mais próximo depois da frase (o pé desta coluna, o topo da seguinte ou uma faixa da página seguinte), enquanto esta frase e o texto depois dela seguem sem interrupção.

O texto corrido nunca é interrompido no ponto da referência. Onde o recurso fica (no primeiro espaço livre, ou só num espaço no topo ou no pé; numa única coluna ou na largura toda) depende do seu posicionamento (veja Posicionamento abaixo) e de onde você o menciona: a busca começa logo depois da referência.

#Inserção em bloco (opcional, posicionamento explícito em linha)

Às vezes você quer que um recurso fique num ponto exato do fluxo em vez de flutuar. Desative a flutuação dando ao recurso placement.position: "here" e inserindo-o com ::resource{id="…"} numa linha própria:

Here is the floor plan we discussed.
 
::resource{id="lighthouse-diagram"}
 
The keeper's quarters occupy the eastern wing.

Para um recurso flutuante, a diretiva ::resource é desnecessária: o :ref já o posicionou, e um ::resource redundante para o mesmo id é tratado apenas como mais uma referência, não como uma segunda cópia. Um ::resource só renderiza o recurso em linha quando o posicionamento resolvido é "here". Um recurso em linha mantém uma linha de espaço acima dele (o espaço de flutuante), como faria um flutuante, a menos que o bloco anterior peça mais. No texto corrido ele mantém o mesmo espaço abaixo; depois, o texto que vem em seguida volta para a grade de linhas de base, o que pode acrescentar até mais uma linha. Um título, uma lista, um boxe ou outro recurso em linha logo depois dele divide esse espaço com o seu próprio espaço acima: vale o maior dos dois, não a soma. (Até o postext 1.4, o espaço abaixo era só o que o encaixe na grade deixava, de nada até uma linha; layout.inlineResourceGap: 'above' mantém essa regra, e os livros salvos antes do 1.5 são lidos com ela.) Dentro de um boxe (:::callout), o recurso mantém o mesmo espaço, uma linha do próprio texto do boxe acima dele e, com 'around', abaixo; no topo ou no pé do boxe, quem o separa é o preenchimento. (Até o postext 1.4, ele ficava encostado no texto do boxe; layout.inlineResourceGapInBoxes: false mantém isso, e os livros salvos antes do 1.5 cujos boxes inserem um recurso são lidos com essa opção.)

Um recurso em linha cujo posicionamento também diz span: 'page' (placement: { position: 'here', span: 'page' }) ocupa a página no ponto da sua diretiva num layout de várias colunas, como faz um boxe que ocupa a página: as colunas acima dele se fecham niveladas (balanceadas, ou o recurso vai para o topo da página seguinte quando isso não é possível), ele é composto na largura do conteúdo com o mesmo espaço acima e abaixo, e o texto continua em todas as colunas embaixo dele. Numa página de uma coluna, ele é composto como antes, na medida inteira. Um recurso span: 'column' com columns definido fica na sua coluna quando é inserido em linha: as colunas só contam para os flutuantes. Desde o postext 1.19.

O id precisa corresponder a um recurso definido no painel Recursos. O motor renderiza o recurso (bitmap, SVG ou tabela) com a legenda desenhada embaixo, como pé de figura ou de tabela. O texto da legenda é formado pelo captionPrefix do tipo de recurso, pelo número calculado e pela legenda do próprio recurso, por exemplo Figura 1.7. A planta original do farol. Sua tipografia é regida por Configuração › Estilo de legenda: o rótulo e a descrição compartilham uma família tipográfica e um tamanho, enquanto o rótulo mantém configurações independentes de negrito, itálico e cor; o espaço acima da legenda é 0.75em por padrão e o alinhamento é à esquerda. A legenda pode, em vez disso, ficar acima do recurso (captionStyle.position: 'above', de forma global ou por tipo de recurso), opcionalmente sobre uma barra colorida. Um recurso também pode ter uma note (uma linha curta de fonte ou de crédito, com a mesma formatação em linha e as mesmas marcas :ref da legenda), composta num corpo menor sob o recurso (sob a legenda quando a legenda fica embaixo, sob o corpo quando fica em cima) e estilizada por captionStyle.note.

Quebras de linha em legendas e notas. Uma legenda ou uma nota é um parágrafo composto na medida do seu espaço, e uma quebra de linha digitada nela vale como espaço. Para começar uma linha nova, escreva \\ (a quebra forçada dos títulos) ou termine a linha com uma barra invertida, a quebra forçada do Markdown: ¹ Measured at 20 °C. \\ ² Mean of three runs. compõe cada nota de uma tabela larga numa linha própria. A linha antes de uma quebra mantém sua largura natural, sem ser esticada até a medida, e duas quebras seguidas não criam uma linha vazia (um espaço inseparável entre elas cria). Numa célula de tabela, \\ faz o mesmo que uma quebra de linha: abre um parágrafo novo; o recuo da linha seguinte é mantido, de modo que dois espaços iniciais ainda aninham um item de lista. No próprio texto as duas barras invertidas são sempre uma quebra, sem escape: para imprimi-las, ponha-as em código em linha, onde as barras invertidas saem como foram escritas. No destino de um link elas continuam fazendo parte da URL, e nos atributos de uma diretiva (o text de um :ref) fazem parte do valor; dentro de um chip, que é composto numa só linha, uma quebra vale como espaço. (Até o postext 1.4, as barras invertidas eram impressas, e uma legenda ou uma nota só quebrava onde a medida acabava.)

Os recursos de tabela desenham a própria grade, estilizada por Configuração › Estilo de tabela: as células do corpo e do cabeçalho têm tipografia totalmente independente, o fundo do cabeçalho é #f0f0f0 por padrão, as bordas 0.75pt, e cellPadding 0.375em; qualquer campo não definido herda do texto do corpo. As larguras das colunas fazem parte da própria tabela: TableModel.columnWidths guarda um peso relativo por coluna ([2, 1, 1] dá à primeira coluna metade da largura); quando não definido, as colunas dividem a largura por igual. Uma tabela também pode ser composta numa variante nomeada: table.styleId escolhe um dos tableStyles do documento (veja Configuração › Estilos de tabela nomeados), cujos campos não definidos herdam de tableStyle; um id desconhecido ou ausente mantém tableStyle.

Uma célula posiciona seu conteúdo com TableCell.align (left, center, right; os itens de lista ficam alinhados à esquerda) e TableCell.verticalAlign (top, o padrão, middle ou bottom). O alinhamento vertical move todo o conteúdo da célula (a imagem e o texto embaixo dela, como uma unidade) dentro de uma célula mais alta que ele: uma linha esticada por uma vizinha mais longa, ou as linhas que um rowSpan cobre. Vale em todas as saídas (canvas, HTML, PDF), em tabelas giradas e em cada fatia de uma tabela dividida entre páginas. Os dois se definem por célula nos botões de alinhamento da barra de ferramentas do editor de tabelas do Sandbox.

Uma célula de tabela também pode conter uma imagem. TableCell.image indica um recurso bitmap ou SVG pelo id ({ "resourceId": "fig-arm", "width": 0.7 }): a imagem é desenhada dentro da célula (nunca numerada, flutuante nem com legenda), ajustada à largura interna da célula (ou à fração dela indicada por width, padrão 1) mantendo a proporção, alinhada como o texto da célula, e qualquer texto da célula corre embaixo dela. A linha cresce para contê-la. No editor de tabelas do Sandbox, o botão de imagem da barra de ferramentas escolhe o recurso da célula ativa e um campo de largura define a fração. Um id que não corresponde a nenhum recurso de imagem deixa a célula só com texto.

Uma célula pode ter seu próprio preenchimento. TableCell.background é um valor de cor ({ "hex": "#c1dfd6", "model": "hex" }, opcionalmente ligado a uma entrada da paleta do documento com paletteId) pintado no lugar do fundo de cabeçalho ou de corpo do estilo; é assim que uma matriz de compatibilidade colore suas células de verde, vermelho e amarelo. O editor de tabelas do Sandbox o define pelo controle de preenchimento da barra de ferramentas. Para criar a legenda dessas cores, a legenda, a nota e qualquer bloco de texto aceitam uma amostra de cor em linha: :swatch{color="#c1dfd6"} (um hex, ou o id de uma entrada da paleta, :swatch{color="table-compatible"}) compõe um pequeno quadrado sobre a linha de base, com três quartos do tamanho da fonte, preenchido com a cor e contornado na cor do texto, de modo que uma nota pode dizer :swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible. Uma cor que não se resolve em nada desenha um contorno vazio. O hex pode ter canal alfa (#rrggbbaa, #rgba), e cores rgb() / rgba() também funcionam, de modo que um preenchimento de célula translúcido tem uma amostra translúcida correspondente (veja Configuração › Transparência).

Os recursos SVG também podem ser recoloridos para impressão com uma única cor especial por meio de diagramStyle.singleInk (padrão false). Quando ativado, todas as cores de um diagrama SVG são convertidas numa retícula de diagramStyle.inkColor (que por padrão é a cor principal da paleta, #295AA3) proporcional à luminância (o branco vira papel, o preto a tinta cheia), de modo que as figuras se reproduzem fielmente quando o documento é impresso com uma única cor especial. Veja Configuração › Estilo de diagramas.

Uma inserção malformada (id ausente ou vazio, id sem aspas ou com aspas simples, atributos extras) não vira um bloco de recurso; ela passa para a análise comum de parágrafo e continua visível na saída. O mesmo acontece com uma linha de inserção bem formada colada embaixo de uma linha de parágrafo sem linha em branco entre elas: ela é lida como parte desse parágrafo. Os dois casos geram um aviso malformedEmbed, uma entrada Inserção composta como texto no painel Verificações do Sandbox.

As referências em linha são reconhecidas dentro de qualquer bloco de texto (parágrafos, títulos, citações em bloco e itens de lista) e podem conviver com negrito, itálico, código em linha e fórmulas em linha.

Opções de referência

A diretiva :ref aceita três atributos opcionais, em qualquer ordem. style escolhe como o rótulo calculado é renderizado: style="number" imprime só o número (1.7), style="full" imprime o nome completo do tipo mais o número (Figure 1.7), e quando style não é definido usa-se o shortLabel do tipo mais o número (Fig. 1.7). case muda a caixa (maiúsculas ou minúsculas) apenas da parte do rótulo, com lower, upper ou capitalize, sem tocar no número. text é uma substituição literal que troca qualquer rótulo calculado e tem precedência sobre style e case. As opções de renderização lado a lado:

Se um :ref (ou um ::resource) indica um id sem recurso correspondente, o rótulo vira ? (um rótulo text= é impresso em vez disso, ainda sem número nem link) e o Sandbox emite um aviso de Recurso desconhecido. O motor o registra como uma entrada unknownResourceId nos contentWarnings do documento, com o intervalo de origem e a página da referência; isso vale também para um :ref dentro de uma legenda, de uma nota ou de uma célula de tabela de um recurso que o texto usa.

#Numeração pela primeira referência

O número de um recurso é atribuído na primeira vez que ele é mencionado na ordem de leitura, seja essa primeira menção uma inserção em bloco ::resource ou um :ref em linha. A partir daí, toda referência ao mesmo id imprime esse mesmo número.

Isso significa que os números seguem a ordem em que o leitor encontra os recursos, e não a ordem em que eles foram criados no painel:

• Se você faz um :ref a uma figura na introdução e só a insere (::resource) duas páginas depois, ela continua com o número da introdução: a referência veio primeiro.
• Inserir uma referência nova mais cedo no documento renumera automaticamente tudo o que vem depois. Não há numeração manual para manter em dia.

A numeração é por tipo de recurso e respeita o escopo de reinício e o formato de contador de cada tipo; veja Configuração › Tipos de recurso para os tokens de modelo ({h1}, {n}), resetOn e counterFormat.

Só conta o que o texto referencia: um recurso que só um design desenha (um elemento de imagem de uma abertura de capítulo, por exemplo) não recebe número e deixa o contador como estava. E {h1} conta todo título de nível 1 cujo estilo não seja numbered: false, mesmo um cujo numberingTemplate esteja vazio, de modo que um artigo cujo único H1 é o título numera suas figuras como 1.1, 1.2… por padrão. Configuração › O que é numerado traz as duas regras e as configurações para Figura 1, 2….

#Posicionamento

Cada recurso tem um posicionamento que decide onde o flutuante fica, resolvido por recurso (seu próprio placement), depois pelo defaultPlacement do tipo e depois pelo padrão embutido auto / column:

Um flutuante vai para o primeiro espaço livre depois da sua primeira referência, na ordem de leitura: o pé da coluna em que está a referência, depois o topo e o pé da próxima coluna vazia da mesma página, depois as faixas da próxima página que o fluxo abre (um flutuante que ocupa a página fica no pé da página quando todas as colunas ainda têm espaço para ele; caso contrário, numa faixa da página seguinte). Uma página aberta por uma figura ou tabela em linha também conta: um flutuante à espera dessa página ocupa o topo dela, acima da figura ou tabela, quando os dois cabem nela; quando não cabem, a figura ou tabela fica com a página e o flutuante espera a seguinte. Até o postext 1.4, essa página era pulada, e o flutuante esperava a página depois dela mesmo quando os dois cabiam. Ele nunca é reduzido e nunca fica antes da sua referência. Os flutuantes de uma mesma sequência de numeração aparecem na ordem das referências: uma figura que não cabe em lugar nenhum de uma página segura as figuras que vêm atrás dela (uma tabela à espera não segura uma figura, nem o contrário), de modo que a figura 12 nunca aparece antes da figura 11. Uma tabela que, sem isso, teria de esperar é cortada: quando lhe é oferecido o topo de uma coluna vazia, ela ocupa as linhas que cabem e continua no espaço seguinte (a coluna ao lado ou a próxima página), com as linhas de cabeçalho repetidas (veja tableStyle.overflow).

Os flutuantes nunca escapam do seu capítulo: numa abertura de capítulo (um nível de título com breakBefore ou span: 'page'), num :::part, num estilo de boxe com floatBarrier: true (o boxe de “pontos-chave” que fecha um capítulo) e no fim do documento, todo flutuante ainda pendente é posicionado antes, nos espaços livres da página ou em páginas abertas antes da fronteira. Um flutuante citado pela primeira vez pela própria abertura (um título de capítulo que nomeia sua figura), ou pelo primeiro bloco depois de um :::part, pertence ao capítulo novo: ele fica depois dessa linha, como qualquer outro. Uma figura ou tabela que pediu o topo de uma página pode então ocupar o pé da página de fechamento do capítulo, sob as colunas balanceadas, em vez de uma página só para ela. Um :::pagebreak simplesmente manda os flutuantes pendentes para a página que vem depois dele.

As faixas de flutuantes são corrigidas em relação à grade de linhas de base para que o texto em volta mantenha o ritmo vertical da página inteira. Uma faixa no topo aumenta sua margem inferior até a próxima linha da grade, de modo que o texto abaixo do flutuante continua alinhado com as colunas vizinhas e com a página oposta. Um flutuante no pé é ancorado de modo que a última linha da legenda compartilhe uma linha de base com a última linha de texto das outras colunas (um conteúdo sem legenda alinha sua borda inferior à última posição da grade); as páginas cheias, portanto, terminam na mesma altura entre colunas e entre páginas opostas.

Na página de fechamento de um capítulo, e do documento, nada vem depois das figuras e tabelas de página inteira compostas abaixo da última faixa de texto, então elas sobem para ficar a um espaço de flutuante abaixo dela, empilhadas na sua ordem, em vez de deixar um vazio entre o texto e uma figura no pé da página. Isso vale também para um flutuante position: 'bottom'. Para mantê-las no pé, como em todas as outras páginas, defina layout.hugClosingFloats: false (veja Configuração › Layout). Páginas com coluna lateral nunca as movem.

Os três renderizadores (a visualização no canvas, o visualizador HTML e a saída PDF) renderizam recursos. No renderizador HTML, os dados das imagens ficam fora do documento, então o host os fornece pela opção de resolvedor resourceImageUrl(fileId); quando o resolvedor está ausente (ou não retorna nada para um arquivo), o recurso é renderizado como uma caixa neutra de marcação para que o layout fique estável. O arquivo de um vídeo chega do mesmo modo por resourceVideoUrl(fileId) (veja Vídeos).

Onde um flutuante pode ficar

“Nunca antes da sua referência” se conta a partir da linha que cita o flutuante: o flutuante espera até essa linha ser composta e ocupa o primeiro espaço livre depois dela na ordem de leitura; o topo da página em que a linha é composta vem antes dela. Um flutuante lateral (span: 'side', na coluna lateral reservada a flutuantes de um layout de coluna e meia) é a exceção: ele se empilha na coluna lateral ao lado do texto que o cita, e pode ficar mais acima na página que a linha que o cita. Para uma figura citada na página 5:

• Uma página de abertura de capítulo segue as mesmas regras: um flutuante auto ou bottom que ocupa a página, citado no primeiro parágrafo da abertura, pode ocupar a faixa do pé dessa página, sob o texto; um top abre a página seguinte. Para ter a imagem na página que a cita, use auto ou bottom, ou desenhe-a como um elemento de imagem do design da abertura.
• Dois flutuantes de coluna citados no mesmo parágrafo ocupam os dois espaços seguintes: normalmente o primeiro fica no pé da coluna que cita, o segundo no topo da próxima coluna vazia, lado a lado na página.
• Num layout de uma coluna, um flutuante que ocupa a página é um flutuante de coluna, e valem as mesmas regras: um flutuante top citado numa página fica no topo da seguinte.
• Um parágrafo que passa de uma página para a outra também conta a partir da linha que cita. Quando o parágrafo começa no pé da página 5 e a referência cai na página 6 (ou o parágrafo inteiro vai para a página 6, porque não cabem linhas suficientes dele no pé da página 5), a referência está na página 6: um flutuante top abre a página 7, e um auto ocupa o pé da página 6 quando há espaço para ele. O mesmo vale entre as colunas de uma página, e para um boxe dividido entre páginas: uma figura que a segunda parte dele cita espera por essa parte.
• Mudou no postext 1.5. Até o postext 1.4, um flutuante entrava na fila quando o layout chegava ao parágrafo que o cita, de modo que a página para onde esse parágrafo continuava (ou para onde ia) podia abrir com o flutuante, acima da linha que contém a referência. Uma figura assim agora fica uma página depois, ou no pé da página quando pede auto; o número de páginas pode mudar.

#Área segura

Um recurso bitmap ou SVG pode marcar uma área segura: o retângulo da imagem que contém o que importa (uma pessoa e uma faixa da paisagem atrás dela, a parte com o gráfico de um diagrama) e que sempre é mostrado. É o safeArea do recurso, quatro frações (0–1) do tamanho intrínseco da imagem, medidas a partir do canto superior esquerdo: x e width são frações da largura, y e height da altura. O nome diz o que precisa ser mantido; uma caixa de recorte diria onde cortar.

const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // os barcos e o cais: 18–68 % da largura, 25–85 % da altura
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};

Só uma imagem com área segura é recortada. O motor pode então mostrá-la em qualquer proporção entre a imagem inteira e a área segura: mais alta que a proporção da própria imagem, cortando as laterais, no máximo até a largura da área segura, ou mais baixa, cortando em cima e embaixo, no máximo até a altura dela. A largura da figura nunca muda, só a altura. O que fica fora da área segura é cortado dos dois lados em proporção às margens ali, de modo que um motivo à esquerda do centro continua à esquerda do centro. Composto com 60 mm de largura, o porto acima tem 40 mm de altura quando inteiro, e pode ser mostrado com qualquer altura entre 24 mm (cortado em cima e embaixo até 60% da altura) e 80 mm (as laterais cortadas até metade da largura). Valores além das bordas da imagem são limitados a elas; uma área com um valor que não é número, ou um lado menor que 2% da imagem, ou que cobre a imagem inteira, é ignorada, assim como o campo numa tabela. Sem área segura, uma imagem é sempre mostrada inteira, como antes.

O motor usa essa margem em três lugares:

• O espaço que resta numa coluna. Uma imagem em linha (position: 'here') um pouco alta demais para o espaço que resta na sua coluna, inclusive uma cuja legenda passaria do pé da página, é recortada dentro da sua área segura para ficar ali, em vez de seguir para a próxima coluna ou página e deixar esta curta.
• Páginas mais baixas que a figura. Com layout.fitFiguresToPage, uma imagem alta demais para a página é primeiro recortada dentro da sua área segura, mantendo a largura, e só é reduzida se ainda estiver alta demais (veja Configuração › Layout).
• Balanceamento de colunas. Uma imagem com área segura composta em linha numa coluna curta, ou flutuando no topo ou no pé dessa coluna sobre essa coluna apenas, cresce em linhas inteiras da grade de linhas de base para preencher as linhas vazias da coluna. Uma imagem mais alta não deixa buraco visível, então esse recurso de ajuste, flexFigure, é tentado logo depois do boxe que fecha a coluna e antes de qualquer espaço ser acrescentado acima dos títulos ou depois das listas. Um flutuante no topo de uma coluna na página de fechamento de um capítulo ou numa faixa de fechamento não cresce, já que esses topos de coluna ficam nivelados (veja Configuração › Balanceamento de colunas).

A VDT registra o recorte no bloco do recurso: bodySource é a parte da imagem mostrada em bodyRect, nas mesmas frações (ausente quando a imagem inteira o preenche), e bodyFlex dá os px que o corpo ainda poderia encolher e crescer e os px em que os ajustes já o alteraram ({ shrink, grow, delta }). A visualização no canvas e o PDF recortam no corpo e desenham a imagem inteira no tamanho sem recorte; o visualizador HTML e o EPUB de layout fixo compõem a imagem com object-fit: cover e um object-position correspondente; um EPUB refluível, que não tem página a preencher, mostra a imagem inteira. Um host que desenha as imagens por conta própria pode usar as funções auxiliares que o postext exporta: resourceSafeArea e normalizeSafeArea (a área como o motor a lê, ou undefined), safeAreaHeightRange (o corpo mais baixo e o mais alto numa dada largura), safeAreaSource (a parte mostrada numa dada altura) e uncroppedPictureBox (onde desenhar a imagem inteira antes de recortar), com o tipo ResourceSafeArea. No Sandbox, o campo é Área segura, numa imagem do painel Recursos.

A receita Nº 116 das Receitas, Fotos que crescem para preencher uma coluna curta, compõe uma reportagem de revista em duas colunas duas vezes, sem e com áreas seguras, para que você compare as páginas lado a lado.

#Âncoras de falante e zonas a evitar

Uma imagem que é a arte de um quadro de quadrinhos também pode dizer onde estão as personagens, para o letreiramento (veja Quadrinhos). anchors lista um ponto por falante e avoid as regiões que nenhum balão cobre, ambos em frações da imagem, como a área segura:

const radio: Resource = {
  id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 },
  safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 },
  anchors: [
    // o faroleiro: boca, cabeça (para balões de pensamento) e rosto
    { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } },
  ],
  avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // o rádio
};

O id de uma âncora é a chave de falante do roteiro (tomas: …), ou sfx para o ponto onde se reúnem as onomatopeias do quadro; x e y são a boca para onde aponta o rabicho de um balão de fala, head o ponto para onde apontam as bolinhas de um balão de pensamento (a boca, quando não definido) e face um retângulo que nenhum balão cobre. O motor projeta cada ponto pelo recorte e pelo espelhamento do quadro, de modo que um rabicho continua no seu falante seja qual for a forma do quadro; uma âncora fora da área segura gera comicAnchorOutsideSafeArea, porque um recorte pode cortá-la. As âncoras pertencem à imagem e servem a todas as traduções dos quadrinhos. Só os quadros de quadrinhos as leem; uma figura as ignora. No Sandbox, elas são marcadas no diálogo Área segura e letreiramento do painel Recursos.

#Vídeos

Um recurso de vídeo (kind: 'video') é um vídeo do YouTube ou do Vimeo, ou um vídeo seu: um arquivo guardado no livro (MP4, WebM) ou um que está num endereço da web, seja um arquivo num servidor ou um stream HLS (uma playlist .m3u8). Ele é posicionado, legendado, flutuado e citado como uma imagem, e numerado numa sequência própria: o tipo embutido video imprime Vídeo 1.1, Vídeo 1.2… ao lado de Figura 1.1 e Tabela 1.1 (veja Configuração › Tipos de recurso). Cada saída o mostra como pode:

const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // toca a partir de 0:30; o link impresso também começa aí
  },
};

O texto cita um vídeo como cita uma figura: :ref{id="keeper-talk"} imprime Vídeo 1.1 e faz o pôster flutuar para o primeiro espaço livre depois da referência, e ::resource{id="keeper-talk"} com placement.position: 'here' o coloca no fluxo do texto. Os campos de Resource.video (ResourceVideo):

O pôster. Ele é composto na medida do seu espaço (ou na fração placement.width dela), na sua própria proporção, seja qual for o seu tamanho em pixels: um quadro do tamanho de uma tela é ampliado em vez de sair impresso pequeno. Como um bitmap, pode ter uma área segura e seguir placement.align. Um vídeo sem pôster imprime uma caixa escura na proporção do vídeo (16:9 quando nada a indica) com as suas sobreposições e gera um aviso de conteúdo videoWithoutPoster. No Sandbox, o pôster de um vídeo do YouTube ou do Vimeo é buscado na plataforma quando o endereço é digitado, e o de um arquivo é um quadro que você escolhe no vídeo.

O endereço. O código QR e o link do PDF abrem a página do vídeo, https://youtu.be/<id> ou https://vimeo.com/<id>, a partir de start. Um arquivo não tem página: eles abrem o seu endereço de produção, que é também de onde toca um vídeo sem arquivo próprio (um MP4 num servidor, um stream HLS). Sem endereço, a impressão fica sem código QR e sem link (videoWithoutUrl), e uma saída HTML ou EPUB que não carrega o arquivo mostra o pôster. Um endereço do YouTube ou do Vimeo que não aponta para nenhum vídeo da plataforma gera videoUrlInvalid; o pôster aparece no lugar de um player.

Os players. As opções de player (controles, botão de download, tela cheia, menu de velocidade, picture-in-picture, transmissão para outra tela, reprodução automática, início sem som, repetição, pré-carregamento, incorporações com privacidade reforçada) são definidas para o livro inteiro em videoStyle.player e para um vídeo em video.player; cada player respeita o que consegue (veja Configuração › Estilo de vídeo). O renderizador HTML recebe a URL reproduzível de um arquivo pela opção resourceVideoUrl(fileId), assim como recebe as imagens por resourceImageUrl, e na falta dela usa o endereço de produção. A sua opção videos: { files, streams, hls } escolhe entre player e pôster por origem, por cima de videoStyle.html (hls, um vídeo reproduzido a partir de um endereço HLS, segue files se não for definido); o gerador de EPUB a utiliza. Um <video> que reproduz um endereço HLS leva data-pt-hls, para que um host possa lhe dar um player nos navegadores sem HLS nativo (o Safari e as versões recentes do Chrome o reproduzem como está). Num livro da direita para a esquerda, o player e as sobreposições do pôster são desespelhados como uma imagem, para que o código QR possa ser lido.

Na VDT. O bloco de recurso de um vídeo tem kind: 'video', o seu pôster como fileId / format (desenhado como um bitmap) e video (VDTResourceVideo): o link para onde o leitor é levado, o embedUrl do YouTube ou do Vimeo com as opções de player aplicadas, o fileId de um arquivo, o mimeType de um vídeo seu (do arquivo ou apenas do endereço, application/vnd.apple.mpegurl para HLS), o intervalo start / end, o player resolvido, linkPoster, html e as sobreposições playMark e qr (os módulos do QR como linhas de '0' / '1'), com retângulos relativos ao canto superior esquerdo do corpo. Um host que desenhe os vídeos por conta própria pode usar os auxiliares que o postext exporta: parseVideoUrl, videoWatchUrl, resourceVideoLink, videoEmbedUrl, videoEmbedAllow, videoElementAttributes, mediaFragment, videoMimeType, videoFormatOfUrl, resourceVideoFormat, isHlsMimeType, HLS_MIME_TYPE, youtubePosterUrls, encodeQr, layoutVideo, playMarkTriangle e qrModuleRuns.

Num pacote. Um .postext carrega o arquivo (resources/<id>.mp4) e o pôster (resources/<id>.poster.jpg): a entrada do manifesto os nomeia em file e poster, informa o tamanho do pôster em width / height e guarda o resto em video, sem os ids de arquivo. bundleVideoUrl(bundle) é o resolvedor resourceVideoUrl sobre os arquivos de um pacote. Um vídeo reproduzido apenas a partir de um endereço não carrega arquivo: a sua entrada tem só o pôster. Num pacote bilíngue, um idioma pode dar a um vídeo o seu próprio poster e video (outra edição, no seu próprio endereço) em localized[…].resources.

Vídeos nas páginas do Folio

No livro 3D, um vídeo seu toca na página em que está impresso. Um clique no pôster o inicia ali, seja qual for a função do ponteiro no livro (virar páginas, girar a vista ou selecionar texto): o shader da página desenha os quadros do vídeo sobre o pôster, de modo que a imagem se dobra e se curva com o papel enquanto a folha vira, e continua tocando durante a virada. Um clique num vídeo em reprodução o pausa, um clique num vídeo pausado o retoma, e Espaço ou Enter fazem o mesmo com o primeiro vídeo da página dupla aberta. Iniciar outro vídeo interrompe o que está tocando (ele volta ao pôster), e um vídeo para quando o livro se acomoda numa página dupla que já não o mostra, ou ao chegar ao seu end. O ponteiro vira uma mão sobre um vídeo que pode ser reproduzido; um arrasto que começa sobre ele continua virando a página ou a vista. Um vídeo configurado para tocar sozinho (video.player.autoplay) começa por conta própria na primeira vez que o livro se acomoda na sua página dupla, depois que o livro se estabiliza (inclusive quando um host o diagrama em etapas), e nunca mais nesse visualizador.

Um vídeo que toca junto com os outros (video.player.exclusive: false, desde o postext 1.18) muda as duas regras. Iniciá-lo interrompe apenas os vídeos exclusivos, de modo que vários vídeos desse tipo tocam ao mesmo tempo; iniciar um vídeo exclusivo também o interrompe. Com autoplay, ele começa sem som cada vez que o livro se acomoda na sua página dupla e para quando a página dupla é virada: os loops silenciosos (loop) de uma página rodam juntos toda vez que o leitor chega a ela.

• O que toca. Um arquivo (o host converte o seu fileId numa URL com a opção videoUrl; no Sandbox, uma URL de objeto) ou, na falta dele, o seu endereço: MP4, WebM ou um stream HLS. Um stream HLS toca pelo hls.js onde o navegador tiver Media Source Extensions (carregado na primeira reprodução; uma dependência par opcional do postext-folio), limitado à variante mais próxima do tamanho da imagem na tela, para que uma imagem de algumas centenas de pixels de altura nunca puxe uma variante 4K; o HLS do próprio navegador é a alternativa. As suas requisições levam uma query pt-cors própria, para que o cache do navegador nunca lhes entregue uma cópia que outro player buscou sem CORS. O YouTube e o Vimeo tocam em iframes, que o WebGL não consegue desenhar: um clique no pôster deles vira a página como em qualquer outro ponto.
• Leituras entre origens. O WebGL só desenha um vídeo quando o servidor permite a leitura (CORS, Access-Control-Allow-Origin). Um vídeo que não pode ser lido continua sendo um pôster, e onVideo recebe error.
• Som. O clique permite que o vídeo toque com som; um navegador que ainda assim recuse o recebe sem som. Um vídeo que começa sozinho tem som depois que o leitor clicou ou digitou na página (virar até ela conta); antes disso, começa sem som, e um clique nele ativa o som antes que o clique seguinte o pause. video.player.muted o inicia sem som, loop o reproduz de novo, e start / end delimitam o trecho que toca.
• Em qualquer página. A imagem é desenhada onde o layout a coloca: girada com um recurso girado, em pé numa página vertical e sem espelhamento num livro da direita para a esquerda, como o pôster. Um pôster recortado dentro da sua área segura recorta o vídeo da mesma forma.
• Sem WebGL2, ou com movimento reduzido, o vídeo toca num <video> HTML sobreposto à página.

const book = createFolioFromDocument(container, doc, {
  // A URL reproduzível de um vídeo enviado (uma URL de objeto sobre os seus bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();

videos: false desativa isso. toggleVideoAt({ page, x, y }) faz o que um clique naquele ponto faria, e pageVideoSpots(page, doc) lista onde fica cada vídeo numa página, para um host que desenhe os próprios controles.

Duas receitas das Receitas compõem vídeos: a Nº 131, Um programa de cineclube com códigos QR nos pôsteres, imprime cada filme como um cartão de título com uma marca de reprodução e um código QR, e a Nº 132, Uma ficha de laboratório cujos clipes tocam na tela e no EPUB, define as opções de player da edição HTML e empacota os próprios clipes num EPUB de layout fixo.

#Quadrinhos

As páginas de quadrinhos, as tiras e as páginas duplas são escritas em dois blocos cercados cujo corpo o próprio motor lê, linha por linha: :::page e :::strip. Dentro deles, as linhas ::panel iniciam os quadros e as linhas de roteiro fazem o letreiramento. O guia, com as regras de diagramação, o letreiramento e as saídas, é Quadrinhos; as configurações estão em Configuração › Quadrinhos.

#:::page

:::page{split="30 [30 | 20 | *] / *" gutter=4mm}
::panel{art=lh-arrive}
caption: Every summer, Maya spent a week at the lighthouse.
maya: Grandpa! I'm here!
::panel{art=lh-radio focus="40% 50%"}
tomas: Just in time.
::panel{art=lh-maya}
maya{thought}: That valve looks loose…
::panel{art=lh-beam bleed}
sfx{rotate=-8}: KRAK
:::

Um bloco :::page é uma página de quadrinhos: abre uma página nova, ocupa-a inteira, e o texto depois do seu ::: de fechamento começa na página seguinte. Os seus atributos são split (como a página é dividida em células: tamanhos em porcentagem separados por / para as fileiras e por | para os quadros lado a lado, uma lista entre colchetes para dividir uma célula de novo, * para o restante, a~b para uma linha inclinada), gutter (uma medida, ou duas: entre fileiras e entre quadros; um número sem unidade está em milímetros), style (um estilo de quadro nomeado), bleed, direction (ltr ou rtl, também escrito dir) e spread (veja Páginas duplas). Sem split, os quadros são empilhados em fileiras iguais. Dentro do bloco não são lidos blocos de Markdown, contêineres nem diretivas; os comentários <!-- comments -->, sim.

#Quadros

Uma linha ::panel{…} inicia um quadro, que ocupa a próxima célula na ordem de leitura e vai até a próxima linha ::panel ou até a cerca de fechamento:

#Linhas de roteiro

Cada linha de um quadro é um balão, um recordatório ou uma onomatopeia, escrita key{attributes}: text:

maya: Grandpa! I'm here!
tomas{whisper}: Shh. Listen.
caption{at=bottom-end}: Three streets away.
sfx{at="62% 40%" rotate=-8 size=1.4}: KRAK
ben{tail=start}: (from off the panel) Over here!
sfx{vertical size=2.6 font="Dela Gothic One"}: ドン
maya: This line goes on
  on the next line,\
  and breaks here.

• A chave é um id de personagem (letras, algarismos, _, ., -), o mesmo em todas as traduções; caption, sfx e note são reservadas. Os dois-pontos podem ser os de largura total, ：.
• Uma palavra solta entre as chaves é um estilo de balão (thought, whisper, shout, radio, inner ou um de comics.balloonStyles); style= diz o mesmo.
• at fixa o balão: um ponto em porcentagens do desenho do quadro (at="62% 40%"), ou um canto ou uma borda (top-start, top-end, bottom-start, bottom-end, top, bottom). to aponta o rabicho para um ponto do desenho; tail=none o remove e tail=top|bottom|start|end o aponta para fora do quadro. join e join=false unem o balão ao anterior do mesmo personagem ou o mantêm separado; break deixa que ele atravesse a borda, e a travessia não é reportada como transbordamento. rotate (graus), size (uma escala, para as onomatopeias), color e font mudam o seu letreiramento.
• vertical e horizontal (ou mode=vertical, mode=horizontal) definem a direção de escrita da linha por cima da do livro: um ドン sem tradução, composto em coluna numa edição horizontal; uma placa escrita na horizontal, composta em linha numa edição vertical. Uma coluna num livro de outro idioma segue as regras do seu próprio texto (com kana, as do japonês). Num livro vertical, uma linha sem caracteres chineses nem japoneses é composta em linha de qualquer forma.
• Uma linha recuada com dois espaços ou uma tabulação continua o balão de cima; uma barra invertida no fim de uma linha quebra o texto ali. As linhas em branco são ignoradas.
• O texto é Markdown em linha: ênfase (letreirada em negrito itálico), :tcy, :ruby (a leitura composta sobre a base, exceto sobre uma base da direita para a esquerda), :ltr e :rtl (um trecho que mantém a sua própria direção). Notas de rodapé e marcas :ref não são lidas.

#:::strip

:::strip{split="* | * | *" aspect=3 span=page placement=top}
::panel{art=pip-1}
pip: Morning, Otto!
::panel{art=pip-2}
::panel{art=pip-3}
otto: Is it?
:::

Um :::strip tem o corpo de uma página, mas fica no texto como uma única caixa indivisível, dividida em quadros: span (column, o padrão, ou page), placement (here, o padrão, onde está escrito; ou top, bottom, auto, flutuando como uma figura) e o seu tamanho, seja height (uma medida; um número sem unidade está em milímetros) ou aspect (largura sobre altura: 3, 4/1, 4:1; por padrão, as proporções que deixam os seus quadros quadrados). Uma tira da largura da página posta em here numa página de várias colunas corta as colunas onde está, como faz uma caixa da largura da página. width a deixa mais estreita que a medida que ela ocupa (60% dela, ou uma medida) e align a coloca no início (start), no centro (center, o padrão) ou no fim (end) dessa medida, no sentido do texto. caption="…" põe embaixo dela uma legenda no estilo de legenda; com type=figure (um tipo de recurso), a legenda recebe o rótulo e o número do tipo e a tira entra na sequência desse tipo, e com id=… um :ref a cita. Sem split, os quadros ficam lado a lado. As tiras só são lidas no nível superior de um capítulo.

#Páginas duplas

:::page{spread} estende uma página por duas páginas frente a frente: a divisão cobre as duas manchas de texto unidas na lombada, sem as margens internas, e um quadro pode atravessar a lombada. A página dupla começa numa página par, depois de uma página em branco quando necessário. Veja Quadrinhos › Páginas duplas.

#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 (#).
• Blocos de código cercados ou recuados: cercas ``` ou ~~~ e recuo de 4 espaços. As linhas de dentro são lidas como Markdown comum, não mantidas como listagem: linhas sem linha em branco entre elas se juntam num só parágrafo e perdem os espaços iniciais, uma linha que começa com # e um espaço vira título (#!/usr/bin/env continua texto) e uma que começa com - ou 1. e um espaço vira item de lista, um par de sinais $ vira fórmula, e as linhas da cerca saem impressas como texto: uma cerca ``` como um único acento grave, a de abertura seguida da info string ( `bash), e uma cerca ~~~ como um pequeno ~ composto como subscrito. Para compor uma listagem, escreva cada linha como um parágrafo próprio (com uma linha em branco entre as linhas) dentro de um bloco :::paragraphs cujo estilo de parágrafo defina uma fontFamily monoespaçada, e envolva cada linha em acentos graves, que mantêm #, $, * e o resto como foram escritos. Os espaços comuns no início de uma linha são descartados e uma sequência deles dentro de uma linha se reduz a um, também dentro dos acentos graves; por isso, recue e alinhe com espaços inseparáveis (U+00A0) e coloque-os dentro dos acentos graves: um antes do acento grave de abertura também é descartado. O código em linha é reconhecido, mas não tem fonte de código: veja Formatação em linha.
• Passagem de HTML: <tags> brutas não são interpretadas. Tags no estilo MDX também não são suportadas; o código-fonte 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>.
• Tachado: ~~text~~. O renderizador de tachado está reservado, por ora, aos itens de tarefa concluídos.
• 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 a sua região espera (veja Composição chinesa). O japonês é composto com as suas próprias regras, 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 sob 1. , quatro sob 10. , como o CommonMark aninha as listas; dois espaços sob 1. também aninham. Um item se aninha sob o item aberto mais próximo cujo marcador esteja pelo menos duas colunas à sua esquerda; 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 era floor(spaces / 2) + 1, e um 1. sob 1. 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), então aninhar exige um item acima sob o qual aninhar.
• 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. O ![alt](src) em 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, então 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: ：：： numa cerca, ＃ num título, ［＾1］ num marcador de nota de rodapé, ｛…｝ em atributos, ＊＊ para negrito. Elas saem impressas como texto, e a compilação reporta a linha com um aviso fullwidthMarkup que 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.
   a. Tighter at short measures.
   b. 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.