# Formato do documento > O subconjunto de Markdown que o Postext lê e as regras para escrever os documentos de origem - Versão HTML: https://postext.dev/pt/docs/document-format - Última atualização: 2026-10-07 - Tempo de leitura: 10 min - Outros idiomas: [en](https://postext.dev/en/docs/document-format.md), [es](https://postext.dev/es/docs/document-format.md), [ca](https://postext.dev/ca/docs/document-format.md), [zh](https://postext.dev/zh/docs/document-format.md), [ja](https://postext.dev/ja/docs/document-format.md), [ar](https://postext.dev/ar/docs/document-format.md) ## Em poucas palavras Esta página explica como escrever um texto que o Postext consiga diagramar. Você escreve em Markdown, um jeito simples de escrever em que alguns símbolos marcam títulos, listas, palavras em negrito e links. O Postext também entende algumas marcas a mais para boxes, notas de rodapé, imagens, tabelas e fórmulas. A página lista todas as marcas que ele aceita e as que ele ignora. No final, traz conselhos para escrever um texto fácil de ler. **O Postext lê um dialeto de Markdown pequeno de propósito.** O analisador é um tokenizador escrito à mão, e não uma implementação completa do CommonMark, 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](https://postext.dev/pt/docs/configuration.md#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 `---`: ```md --- 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`](https://github.com/jonschlinkert/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. > **Figura: As construções de bloco de texto, de relance** > Os sete tipos de bloco de texto que o Postext reconhece: título, parágrafo, citação, lista não ordenada, lista ordenada, lista de tarefas e fórmula destacada, cada um com a sua sintaxe em Markdown. As diretivas e os recursos incorporados são tratados à parte. > > *Cada tipo de bloco de texto e a sua forma de entrada em Markdown.* | Construção | Sintaxe | Observações | | --- | --- | --- | | Título | `# Title` … `###### H6` | De um a seis caracteres `#`, seguidos de um espaço e do texto do título. Os níveis 1–6 correspondem diretamente à configuração `headings.levels`. | | Parágrafo | Texto simples em uma ou mais linhas | Linhas consecutivas que não estão em branco nem são especiais são unidas com um único espaço e saem como um só parágrafo. Entre dois caracteres chineses ou japoneses (ideogramas, kana, pontuação de largura total, e aspas curvas, travessões ou reticências ao lado deles), a quebra de linha é descartada, como faz o CSS, então um parágrafo em chinês pode ser quebrado em qualquer ponto do texto de origem. Entre duas dessas marcas (`“你好”⏎“再见”`, `他说……⏎“好”`), decidem os caracteres que vêm depois delas: a quebra de linha some quando um deles é chinês ou japonês, e `“hello”⏎“bye”` mantém o espaço. O coreano mantém o espaço. Quebras de linha manuais dentro de um parágrafo não são preservadas; use uma linha em branco para começar um parágrafo novo. | | Citação | `> quoted text` | Cada linha da citação precisa começar com `>` (com um espaço opcional depois). Linhas de citação consecutivas se juntam em um único bloco de citação, unidas como as linhas de um parágrafo. Ela é composta como diz `bodyText.blockquote`: itálico cinza com o recuo de primeira linha do corpo, a menos que você mude isso (veja [Configuração › Citações](https://postext.dev/pt/docs/configuration.md#citações)). | | Lista não ordenada | `- item`, `* item`, `+ item` | Qualquer um dos três marcadores é aceito. Um item fica aninhado sob o item de cima quando o seu marcador está recuado pelo menos duas colunas além do marcador desse item: dois espaços sob `-`, dois ou três sob `1.` (a coluna do seu texto, como no CommonMark), até uma profundidade máxima de 5. | | Lista ordenada | `1. item`, `2) item` | Algarismos seguidos de `.` ou `)`. O número inicial é preservado (uma lista pode começar em 5, ou em 0). O separador que aparece na saída vem de `orderedLists.separator`, não do texto de origem. | | Lista de tarefas (GFM) | `- [ ] todo`, `- [x] done` | Um item não ordenado com uma caixa de seleção entre colchetes. Aceita `x` minúsculo ou `X` maiúsculo. É desenhado com os glifos `taskCheckboxChar` / `taskCheckedChar`. | | Fórmula destacada | `$$ … $$` | Uma fórmula LaTeX composta como bloco próprio. Sai centralizada na coluna, ajustada à grade de linhas de base como um título, e se mantém vetorial na saída em PDF. As formas de uma linha e de várias linhas entre cercas são descritas em [Fórmulas matemáticas](https://postext.dev/pt/docs/document-format.md#fórmulas-matemáticas). | 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. > **Figura: Profundidade de aninhamento das listas** > Um item de lista fica aninhado sob o item de cima quando está recuado além do marcador desse item: dois espaços sob um marcador, até uma profundidade máxima de cinco. Cada nível recua mais e pode usar outro estilo de marcador. > > *Dois espaços por nível sob um marcador. Profundidade máxima: cinco.* ### 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: ```markdown # 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.}`: 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](https://postext.dev/pt/docs/document-format.md#referências-cruzadas-e-âncoras). 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=""` aplica um [estilo de título](https://postext.dev/pt/docs/configuration.md#estilos-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`: ```markdown # 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](https://postext.dev/pt/docs/configuration.md#sobrescritas-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: ```markdown # 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. | Sintaxe | Efeito | | --- | --- | | `:::pagebreak` | Faz o bloco seguinte abrir em uma página nova. | | `:::pagebreak{parity="odd"}` | O mesmo, garantindo que a página nova seja ímpar (à direita). Insere uma página em branco de preenchimento quando necessário. | | `:::pagebreak{parity="even"}` | O mesmo, mas visando uma página par (à esquerda). | | `:::pagebreak{parity="always-odd"}` | Garante pelo menos uma página separadora em branco obrigatória antes de chegar a uma página ímpar. A página separadora pertence ao conteúdo anterior; qualquer página de preenchimento a mais, por paridade, pertence ao que vem depois. Útil quando cada capítulo precisa começar em uma página dupla nova. | | `:::pagebreak{parity="always-even"}` | O mesmo, mas visando uma página par. | | `:::numbering{format="decimal" startAt=1}` | Na próxima mudança de página, troca a sequência de numeração das páginas. Os dois atributos são opcionais: omita `format` para manter o formato e omita `startAt` para continuar o contador. | | `:::columnbreak` | Encerra a coluna atual aqui: o bloco seguinte abre na próxima coluna da mesma página (ou em uma página nova, quando a diretiva cai na última coluna). Não faz nada em uma coluna vazia, então nunca produz uma coluna ou página em branco. A coluna que ela encerra mantém o espaço livre no pé; o balanceamento de colunas não a estica. | | `:::space` | Deixa uma linha de corpo em branco aqui: o jeito explícito de dar um pouco de ar entre dois blocos. `:::space{lines=2}` deixa duas (frações como `0.5` também funcionam). O espaço se soma à margem entre os blocos e é descartado no topo de uma coluna ou página. Veja [abaixo](https://postext.dev/pt/docs/document-format.md#space). | | `:::toc` | Imprime o sumário aqui: uma entrada por título dos níveis listados (título, número, número da página e, opcionalmente, os autores do capítulo) e uma linha por divisória de parte, compostas conforme a configuração `toc`. As entradas acompanham o documento: renomeie, mova ou renumere um capítulo e o sumário acompanha. | | `:::index` | Imprime o índice remissivo aqui: todos os termos marcados com `:index` no livro, ordenados e agrupados por letra, com as páginas em que caem, compostos conforme a configuração `index`. `:::index{index="names"}` imprime um índice com nome. Veja [Índice remissivo](https://postext.dev/pt/docs/document-format.md#índice-remissivo). | | `:::page{…}` … `:::` | Uma página de quadrinhos: as suas linhas `::panel` e as linhas de roteiro de cada uma, diagramadas como quadros e balões letreirados em uma página só para elas. Veja [Quadrinhos](https://postext.dev/pt/docs/document-format.md#quadrinhos). | | `:::strip{…}` … `:::` | Uma tira de quadrinhos no fluxo do texto, da largura de uma coluna ou de uma página. Veja [`:::strip`](https://postext.dev/pt/docs/document-format.md#strip). | | `:::verse` … `:::` | Um poema na disposição árabe clássica: um bayt por linha, os seus dois hemistíquios separados por `\|\|` e compostos lado a lado com uma largura comum. Veja [abaixo](https://postext.dev/pt/docs/document-format.md#verse). | 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](https://postext.dev/pt/docs/configuration.md#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. ```markdown # 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](https://postext.dev/pt/docs/document-format.md#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: | Sintaxe | Efeito | | --- | --- | | `:::callout{…}` … `:::` | Conteúdo em boxe: uma nota, dica ou advertência separada do corpo em uma caixa com borda ou fundo colorido. | | `:::paragraphs{…}` … `:::` | Uma sequência de parágrafos composta com um estilo de parágrafo com nome (uma entrada, uma epígrafe, um conjunto de notas em corpo pequeno) em vez do estilo do corpo. `align`, `indent` e `endIndent` definem o alinhamento e os recuos, com ou sem estilo: `:::paragraphs{align=end endIndent=1}` compõe uma data um caractere antes do fim da linha (地から1字上げ). | | `:::part{…}` … `:::` | A abertura de uma parte ou seção: o título e o texto contidos formam a página de abertura de uma divisão principal. | | `:::paper{…}` … `:::` | Uma sequência de páginas impressas em outro papel, como um caderno de pranchas em papel brilhante dentro de um livro em papel fosco. Só o visualizador Folio mostra isso. | Os atributos que cada contêiner aceita, e como ele é estilizado, estão documentados em [Configuração](https://postext.dev/pt/docs/configuration.md). 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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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. ```md :::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: ```md :::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: ```md :::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`: ```md :::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: | Atributo | Valor | | --- | --- | | `type` | O tipo de papel: `uncoated`, `bookWove`, `coatedMatte`, `coatedSilk`, `coatedGloss`, `bible`, `newsprint`, `cardStock`, `board`. Ele define os valores padrão dos atributos abaixo. | | `grammage` | Gramatura em g/m², um número maior que 0. Um papel mais pesado é mais grosso, mais rígido e mais opaco. | | `bulk` | Espessura por peso em cm³/g, um número maior que 0 (espessura em µm = gramatura × bulk). | | `finish` | A superfície: `auto`, `uncoated`, `matte`, `silk`, `gloss`. | | `texture` | O relevo da superfície: `auto`, `smooth`, `vellum`, `wove`, `laid`, `linen`, `felt`. | | `textureStrength` | A intensidade com que a textura aparece, de 0 a 2. | | `shade` | A cor do papel: `#rgb`, `#rrggbb` ou o id de uma entrada de `colorPalette`. | | `showThrough` | `true` ou `false`: se a página do verso aparece levemente por transparência. Um `showThrough` sem valor significa `true`. | 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**). ```md 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`. ```md :::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](https://postext.dev/pt/docs/configuration.md#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: ```md --- 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](https://postext.dev/pt/docs/configuration.md#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. ```md 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. ```md :::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. ```md فأنشد يقول: :::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). ```md # 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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/document-format.md#índice-remissivo). ```md # 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. ```md # 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](https://postext.dev/pt/docs/configuration.md#títulos)). O design de um título imprime `{titleText}` como texto simples em qualquer caso. > **Figura: Formatação em linha num relance** > Comparação entre o Markdown e o resultado renderizado para negrito, itálico, negrito itálico, código em linha e links. > > *Markdown à esquerda, resultado renderizado à direita.* | 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 (`un*believ*able`). 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](https://postext.dev/pt/docs/document-format.md#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](https://postext.dev/pt/docs/document-format.md#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](https://postext.dev/pt/docs/document-format.md#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 | `0` | Os acentos graves são removidos; o trecho é renderizado como texto simples, exatamente como foi escrito: um `:ref{…}`, 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, `\* pOH = −log [OH^−^]`, 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](https://postext.dev/pt/docs/justification.md#onde-uma-linha-nunca-quebra). | | Link | `[texto](https://…)` | 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](https://postext.dev/pt/docs/document-format.md#links). | | Imagem | `![alt](src)` | 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](https://postext.dev/pt/docs/document-format.md#chips-em-linha). | | Fórmula em linha | `$…$` | Uma fórmula LaTeX que flui com o texto em volta, por exemplo `$e^{i\pi}+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](https://postext.dev/pt/docs/document-format.md#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 ``, 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. ```markdown 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]()`). - 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 (``) não são reconhecidos (veja [O que NÃO é suportado](https://postext.dev/pt/docs/document-format.md#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). ```markdown 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. ```markdown 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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#números-em-texto-vertical)). Três marcas destacam um trecho manualmente: ```markdown 第: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](https://postext.dev/pt/docs/configuration.md#elementos-de-texto-verticais)). - 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](https://postext.dev/pt/docs/chinese-layout.md) e [Diagramação em japonês](https://postext.dev/pt/docs/japanese-layout.md) 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. ```markdown 此事: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](https://postext.dev/pt/docs/configuration.md#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. ```markdown :::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](https://postext.dev/pt/docs/arabic-layout.md#direção-e-algoritmo-bidirecional). ## 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. ```md 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é](https://postext.dev/pt/docs/configuration.md#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é](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/document-format.md#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: ```md ## Method {#sec-method} The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}. ``` | `style` | imprime | | --- | --- | | *(nenhum)* | um título numerado pela palavra e pelo número (*seção 3.2*, *capítulo 4*), um título sem número pelo título, uma âncora pelo seu texto, uma equação pelo número como foi impresso (*(3)*), um boxe numerado pelo rótulo e pelo número (*Teorema 2*) | | `number` | só o número (*3.2*, *3*, *2*) | | `title` | o título do título, o texto da âncora ou o `title` do boxe | | `page` | a página em que ficou (*p. 112*) | | `pageNumber` | só o número da página (*112*) | `\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](https://postext.dev/pt/docs/configuration.md#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 ```md 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): ```md --- 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: ```md :::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-`), 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**. | `citations.style` | Nome | Sistema | | --- | --- | --- | | `apa` | APA 7 | autor-data | | `chicago-author-date` | Chicago (autor-data) | autor-data | | `harvard-cite-them-right` | Harvard | autor-data | | `iso690-author-date-en`, `iso690-author-date-es` | ISO 690 | autor-data | | `china-national-standard-gb-t-7714-2025-author-date` | GB/T 7714—2025 著者-出版年 | autor-data | | `china-national-standard-gb-t-7714-2015-author-date` | GB/T 7714—2015 著者-出版年 | autor-data | | `modern-language-association` | MLA 9 | autor-página | | `ieee` | IEEE | numérico | | `elsevier-vancouver` | Vancouver | numérico | | `american-medical-association` | AMA | numérico | | `nature` | Nature | numérico | | `iso690-numeric-en` | ISO 690 | numérico | | `china-national-standard-gb-t-7714-2025-numeric` | GB/T 7714—2025 顺序编码 | numérico | | `china-national-standard-gb-t-7714-2015-numeric` | GB/T 7714—2015 顺序编码 | numérico | | `sist02` | SIST 02 参照文献の書き方 | numérico | | `chicago-notes-bibliography` | Chicago (notas) | notas | | `oscola` | OSCOLA | notas | | `china-national-standard-gb-t-7714-2025-note` | GB/T 7714—2025 注释 | notas | | `china-national-standard-gb-t-7714-2015-note` | GB/T 7714—2015 注释 | notas | 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: ```ts 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. ```md 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. | Atributo | Efeito | | --- | --- | | `term` | A entrada, com os níveis separados por `!`: `term="Heart!valves!mitral"` registra a página em *mitral*, uma subentrada de *valves* sob *Heart*. Um nível pode ter marcas em linha (`term="*Escherichia coli*"`); é ordenado sem elas. Sem `term`, `:index[text]` usa o próprio texto. | | `sub` | Um nível acrescentado depois de `term`: `term="Heart" sub="valves"` equivale a `term="Heart!valves"`. | | `sort` | A chave de ordenação do último nível, quando ele deve ser ordenado por outras letras: `:index[St Kilda]{sort="Saint Kilda"}`, `term="20th century" sort="twentieth century"`. Um índice chinês ordena e agrupa pela leitura que o collator dá a cada caractere. Para um caractere polifônico lido de outro modo, escreva a chave com caracteres que só tenham a leitura desejada: `:index[重阳]{sort="崇阳"}` registra 重阳 em C, entre 程 e 崔, e não em Z. Uma chave em pinyin (`sort="chong yang"`) também chega a C, mas fica depois de todas as entradas chinesas dessa letra, porque o collator põe as letras latinas depois dos caracteres chineses (veja [Configuração › Índice remissivo](https://postext.dev/pt/docs/configuration.md#índice-remissivo), `groupBy`). | | `yomi`, `reading` | A leitura do último nível em kana, pela qual um índice japonês o ordena e agrupa: `:index[夏目漱石]{yomi="なつめそうせき"}` fica em な, na série な行. Sem ele, uma marca cujo texto tem furigana em kana é lida por eles (`:index[{東京\|とう\|きょう}]` é ordenada como とうきょう), depois por `sort`, depois pelo texto; uma entrada que ainda comece por um kanji é sinalizada como `indexReadingMissing`. Num índice em outro idioma, `yomi` funciona como `sort`. Escreva o furigana dentro de uma marca na forma compacta: um `:ruby[…]` exigiria escapar os colchetes. Desde o postext 1.16. | | `main` | Uma flag: o trecho principal sobre o termo. O número da página sai em negrito (`index.main`). Uma página marcada das duas formas sai em negrito. | | `range` | `range="start"` e `range="end"`, com o mesmo termo, delimitam um trecho que ocupa várias páginas: a entrada imprime `34–37`. Um início sem fim, ou um fim sem início, imprime sua única página e gera `indexRangeUnclosed`. | | `see` | Uma remissão no lugar do número da página: `:index{term="Cardiac insufficiency" see="Heart failure"}` imprime *Cardiac insufficiency. See Heart failure*. Os níveis do destino são separados por `!` e saem com dois-pontos (*See Heart: valves*). Um destino que não é entrada do índice gera `indexSeeUnknown`. | | `seealso` | Uma remissão depois dos números de página da entrada: *Heart, 12, 40. See also Circulation*. A página da própria marca conta como a de qualquer outra marca, de modo que uma única marca pode indexar um trecho e apontar para uma entrada relacionada; uma marca `see` não acrescenta página. | | `index` | O nome de um índice separado: `index="names"` registra a marca no índice que `:::index{index="names"}` imprime, e não no principal. | 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](https://postext.dev/pt/docs/configuration.md#estilos-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. ```md # 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](https://postext.dev/pt/docs/japanese-layout.md#índice-remissivo-em-ordem-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](https://postext.dev/pt/docs/configuration.md#í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](https://www.mathjax.org/) 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`](https://postext.dev/pt/docs/configuration.md#matemática). 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](https://postext.dev/pt/docs/document-format.md#referências-cruzadas-e-âncoras). `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](https://postext.dev/pt/docs/configuration.md#matemática)), `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](https://postext.dev/pt/docs/configuration.md#inicializar-o-motor-de-fórmulas)). ```md 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: ```md 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: ```md 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](https://postext.dev/pt/docs/configuration.md#enunciados-numerados-e-demonstrações) para os estilos. ```md :::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](https://postext.dev/pt/docs/sandbox.md#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: ```md 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](https://postext.dev/pt/docs/document-format.md#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: ```md 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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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: | Sintaxe | Renderiza | Observações | | --- | --- | --- | | `:ref{id="…"}` | `Fig. 1.7` | Estilo padrão: o `shortLabel` do tipo seguido do número, unidos por um espaço inseparável para que nunca se separem numa quebra de linha. | | `:ref{id="…" style="number"}` | `1.7` | Só o número calculado, sem rótulo. | | `:ref{id="…" style="full"}` | `Figure 1.7` | O `name` completo do tipo seguido do número. Use no início de uma frase ou onde a abreviatura soa mal. | | `:ref{id="…" case="lower"}` | `fig. 1.7` | Muda a caixa só do rótulo: `lower` (`fig. 1.7`), `upper` (`FIG. 1.7`) ou `capitalize` (primeira letra maiúscula). Combina com `style="full"` (`figure 1.7`); o número nunca é alterado, e um valor não reconhecido é ignorado. | | `:ref{id="…" text="see the plan"}` | `see the plan` | Uma substituição explícita. O texto dado é usado literalmente no lugar de qualquer rótulo calculado; útil para links na prosa como “como vimos antes”. Quando presente, `text` tem precedência sobre `style` e `case`. | 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](https://postext.dev/pt/docs/configuration.md#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](https://postext.dev/pt/docs/configuration.md#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`: | Campo | Valores | Significado | | --- | --- | --- | | `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"` (o padrão) ocupa o primeiro espaço livre depois da referência, no topo ou no pé; `"top"` / `"bottom"` só aceitam espaços desse tipo; `"here"` desativa a flutuação e insere o recurso em linha na diretiva `::resource`. | | `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | Um recurso mais estreito que o seu espaço: `width` é a fração da largura da coluna (ou da página) que ele ocupa, `align` onde ele fica dentro do espaço (uma tabela pequena centralizada na coluna; uma faixa da largura da página cuja imagem ocupa uma coluna). Uma imagem mais estreita que o seu espaço (um bitmap menor que a coluna, ou um que `layout.fitFiguresToPage` reduziu) também fica ali conforme `align`, sob uma legenda que mantém a medida do espaço. Vale tanto para flutuantes quanto para inserções `::resource` em linha. | | `captionSide` | `true` · `false` | Num layout de coluna e meia cuja coluna lateral é reservada para flutuantes (`layout.sideColumnRole: 'floats'`), um flutuante `"column"` com `captionSide` mantém o corpo na coluna principal e compõe a legenda (e a nota) na coluna lateral, alinhada com o topo da figura, ou com o pé no caso de um flutuante no pé; a coluna lateral cede essa faixa. Uma página sem essa coluna mantém a legenda sob a figura. | | `span` | `"column"` · `"page"` | Ocupar uma única coluna, ou interromper o fluxo das colunas e ocupar a largura total do conteúdo, atravessando todas as colunas. Num layout de uma coluna, os dois são idênticos. | | `columns` | um número inteiro, padrão `1` | Numa página de várias colunas, um flutuante `"column"` que atravessa esse número de colunas adjacentes, medianizes incluídas: uma foto ocupando duas das cinco colunas de um jornal. Ele ocupa o topo de uma sequência de colunas vazias que começam niveladas, ou o pé da coluna que o cita e das colunas vazias depois dela. Tantas colunas quantas a página tem, ou mais, o transformam num flutuante que ocupa a página. É ignorado pelos spans `"page"` e `"side"`, por um recurso girado e por uma inserção em linha (`"here"`); `captionSide` só se aplica a um flutuante de uma coluna de largura. Desde o postext 1.18. | | `rotate` | `"ccw"` · `"cw"` | Compõe o recurso girado um quarto de volta: uma tabela em paisagem num livro em retrato. `"ccw"` o gira no sentido anti-horário, com o topo voltado para a borda esquerda da página (o leitor gira o livro no sentido horário), a convenção habitual; `"cw"`, no sentido contrário. Um recurso girado é sempre um flutuante que ocupa a página, numa página própria: ele é diagramado ao longo da altura da área de conteúdo, arredondada para baixo em linhas inteiras da grade de linhas de base e menos uma linha de corpo, o espaço de flutuante que toda faixa de flutuante mantém (uma mancha de 237 mm numa grade de 14 pt comporta 47 linhas, 232,1 mm, então o recurso recebe 46 delas, 227,2 mm); fica encostado na lombada quando as margens são espelhadas (à esquerda, caso contrário), e uma tabela larga demais para uma página é cortada entre linhas e continua, girada, nas páginas seguintes com o cabeçalho repetido, exatamente como uma tabela em pé mais alta que uma página. Uma figura girada é redimensionada para caber na página. Ignorado numa inserção em linha (`"here"`). | 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](https://postext.dev/pt/docs/configuration.md#diagramação)). 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](https://postext.dev/pt/docs/document-format.md#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: | Posicionamento | Na página 5 | Caso contrário | | --- | --- | --- | | `top`, `span: 'page'` | Nunca: a faixa no topo da página fica acima da linha que cita. | A faixa superior da página 6. | | `top`, `span: 'column'` | O topo de uma coluna posterior que ainda está vazia: citada na primeira de duas colunas, pode abrir a segunda. | O topo de uma coluna da página 6. | | `auto` ou `bottom`, `span: 'page'` | A faixa do pé da página 5, quando todas as colunas ainda têm espaço para ela. | Uma faixa da página 6. | | `auto` ou `bottom`, `span: 'column'` | O pé da coluna que cita; depois o pé (qualquer um dos dois) ou o topo (só `auto`) de uma coluna vazia posterior. | Página 6. | - 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. ```ts 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](https://postext.dev/pt/docs/configuration.md#diagramação)). - **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](https://postext.dev/pt/docs/configuration.md#equilíbrio-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](https://postext.dev/pt/docs/sandbox.md#painel-recursos). A receita Nº 116 das Receitas, [Fotos que crescem para preencher uma coluna curta](https://postext.dev/pt/cookbook/photos-fill-short-columns.md), 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](https://postext.dev/pt/docs/document-format.md#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: ```ts 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](https://postext.dev/pt/docs/sandbox.md#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](https://postext.dev/pt/docs/configuration.md#tipos-de-recurso)). Cada saída o mostra como pode: | Saída | O que mostra | | --- | --- | | Canvas, PDF | O **pôster**, um quadro do vídeo, com uma marca de reprodução e um código QR que abre o vídeo ([Configuração › Estilo de vídeo](https://postext.dev/pt/docs/configuration.md#estilo-de-vídeo)). No PDF, o pôster também é um link para o vídeo. | | Folio | O pôster, tal como impresso. Um clique nele reproduz o vídeo **na própria página**, e ele continua tocando enquanto a folha vira (veja [Vídeos nas páginas do Folio](https://postext.dev/pt/docs/document-format.md#vídeos-nas-páginas-do-folio) mais abaixo). Os vídeos do YouTube e do Vimeo continuam sendo pôsteres. | | Visualizador HTML | O **player** do vídeo: o do YouTube ou do Vimeo, ou o player HTML5 do navegador para um arquivo ou um endereço. Um stream HLS toca nativamente no Safari e nas versões recentes do Chrome; nos demais, o host anexa um player como o hls.js, como faz o Sandbox. Com `videoStyle.html: 'poster'`, mostra o pôster impresso no lugar do player. | | EPUB | Um arquivo toca no player do próprio sistema de leitura, empacotado no livro ou lido do seu endereço de produção. Um vídeo do YouTube ou do Vimeo é o seu pôster, com link para o vídeo: um EPUB não pode incorporar o player de uma página da web. Um stream HLS também é o seu pôster com link: uma playlist HLS não é um tipo de mídia que um EPUB possa reproduzir. Onde o sistema de leitura executa scripts, os arquivos de uma mesma página ou capítulo respeitam `player.exclusive`: iniciar um pausa os outros com os quais ele não toca junto. | ```ts 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`): | Campo | Tipo | Significado | | --- | --- | --- | | `source` | `'youtube'` · `'vimeo'` · `'file'` | De onde o vídeo é reproduzido: uma página do YouTube ou do Vimeo, ou um vídeo seu (`'file'`), enviado ou num endereço. | | `url` | `string` | YouTube ou Vimeo: o endereço do vídeo, em qualquer forma (uma página de exibição, `youtu.be`, Shorts, um link de incorporação, `youtube-nocookie.com`; uma página do Vimeo, uma página de canal ou um link não listado com o seu hash). Um arquivo: o seu **endereço de produção**, onde o livro publicado vai encontrá-lo. Um vídeo seu sem arquivo próprio toca a partir desse endereço: um MP4 ou WebM num servidor, ou um stream HLS (`…/master.m3u8`). | | `fileId`, `format` | `string` | Um arquivo: o vídeo enviado, guardado à parte como um bitmap, e o seu formato: `'mp4'`, `'webm'`, `'ogv'`, `'mov'`, ou `'hls'` para um stream HLS. Sem formato, a extensão do endereço o indica (`.m3u8` é `'hls'`); se não, `'mp4'`. | | `poster` | `{ fileId, format, width, height }` | O quadro do pôster, um bitmap. | | `width`, `height`, `duration` | `number` | O tamanho do quadro do vídeo em px (a sua proporção quando não há pôster) e a duração em segundos. | | `posterTime` | `number` | O segundo do arquivo cujo quadro serve de pôster, guardado para poder ser escolhido de novo. | | `start`, `end` | `number` | Reproduz de `start` a `end` segundos. O código QR e o link do PDF também começam em `start`. | | `player` | `VideoPlayerOptions` | As opções de player deste vídeo, aplicadas por cima de `videoStyle.player`. | **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](https://postext.dev/pt/docs/document-format.md#á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/` ou `https://vimeo.com/`, 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](https://postext.dev/pt/docs/configuration.md#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 `