Configuração do Postext

Toda decisão de diagramação no Postext é controlada por um único objeto de configuração.

PostextConfig controla as dimensões da página, a disposição das colunas, a tipografia do texto corrido, os estilos de título, o idioma do documento (locale) e mais. Todas as propriedades são opcionais: o Postext vem com valores padrão sensatos, inspirados na tipografia tradicional do livro. Você só precisa especificar o que quer mudar.

import { buildDocument } from 'postext';
 
const document = buildDocument(content, {
  page: { sizePreset: '21x28', dpi: 300 },
  layout: { layoutType: 'double', gutterWidth: { value: 0.5, unit: 'cm' } },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt substitui o padrão de 8 pt
  headings: { fontFamily: 'Open Sans' },
});

Para uma visão geral de como o motor processa essa configuração, veja a página Arquitetura.

#Índice

Esta referência é longa. Estes são os blocos principais:

• Página — tamanho, margens, grade de linhas de base, marcas de corte, encadernação.
• Diagramação — número de colunas, medianizes, fios, escrita vertical.
• Cabeços e rodapés — elementos de texto e de fio por página, com marcadores, paridade e alinhamento.
• Texto do corpo — tipografia, hifenização, órfãs e viúvas.
• Idioma do documento — o locale de nível superior: alternativa para a hifenização, tipos de recurso embutidos e textos de continuação de tabelas e de boxes divididos, idioma marcado num PDF acessível; os algarismos (numerals) e a direção do texto (direction) que dele decorrem; e os idiomas e sistemas de escrita que o Postext compõe. O guia dos livros da direita para a esquerda é Composição árabe.
• Tipografia do Leste Asiático — cjk: as convenções regionais e a quebra de linha do texto em chinês, japonês e coreano, como suas linhas justificadas se distribuem, as larguras da pontuação e a pontuação pendurada, o espaço entre caracteres Han e latinos, a grade de caracteres, os números em pé no texto vertical, e as marcas, o rubi, as notas warichu e as marcas de kanbun. Os guias de tudo isso são Composição chinesa e Composição japonesa.
• Títulos — padrões comuns e substituições de H1 a H6.
• Listas com marcadores e Listas numeradas — marcadores, numeração, aninhamento.
• Matemática — renderização de LaTeX, escala, cor, margens.
• Tipos de recurso — numeração por tipo para figuras, tabelas e tipos personalizados.
• Estilo de tabela (com estilos de tabela nomeados) e Estilo de legenda — tipografia e decoração das tabelas-recurso e de suas legendas.
• Estilo de diagramas — recoloração a uma só tinta dos diagramas SVG incorporados, para impressão em cor especial.
• Estilos de parágrafo — estilos nomeados para contêineres :::paragraphs: bibliografias, glossários, notas.
• Estilos de boxe — notas, dicas e objetivos em boxe para contêineres :::callout.
• Partes — páginas divisórias de parte para contêineres :::part: paridade, área do corpo, design de abertura, tipografia do corpo.
• Estilos de título — estilos nomeados para títulos {style="…"}: capítulos sem número, elementos pré-textuais com seus próprios cabeços, geometria e paleta.
• Sumário — o que :::toc imprime: tipografia das entradas, linhas de pontos, números de página, linhas de autor, linhas de parte.
• Índice remissivo — o que :::index imprime: tipografia das entradas, recuos, separadores e intervalos de páginas, grupos por letra, idioma de ordenação.
• Quadrinhos — comics: o quadro e as sarjetas das páginas de quadrinhos, os estilos de requadro, o letreiramento, os estilos de balão e o elenco. O guia é Quadrinhos.
• Unidades e cores + Paleta de cores — Dimension, ColorValue, cores nomeadas.
• Fontes personalizadas — declarar famílias tipográficas enviadas pelo usuário ao lado das Google Fonts.
• Visualizador HTML — largura de coluna desejada e quebra de linha para o renderizador HTML.
• Geração de PDF (configuração) — marcadores do documento (outlines), saída acessível (marcada) e espaço de cor forçado para o renderizador PDF.
• Produção gráfica (configuração) — print: PDF/X-1a e PDF/X-4, os perfis de saída ICC, o preto (cinzas só em K, sobreimpressão, preto composto), as cores definidas em CMYK, o preflight e a simulação de impressão.
• Visualizador Folio (configuração) — papel, encadernação, superfície e luz do visualizador de livro em 3D.
• Depuração — sobreposições visuais e avisos de autoria para o editor.
• Uso programático — buildDocument, os avisos que ele informa, resolvers, caches.
• Executar a diagramação num Web Worker — builds fora da thread principal, com cancelamento.
• Integrar o visualizador HTML e Gerar PDFs — receitas completas, de ponta a ponta.
• Livros EPUB — arquivos EPUB 3 de layout fixo e refluível a partir da mesma diagramação, e como verificá-los com o EPUBCheck.

#Página

A propriedade page controla as dimensões físicas e a aparência da página.

#Margens espelhadas

Livros são lidos em páginas duplas, e a margem interna costuma ser diferente da externa. margins.mirror transforma as quatro margens em margens de páginas espelhadas:

{
  "page": {
    "margins": {
      "top": { "value": 2, "unit": "cm" },
      "bottom": { "value": 2.5, "unit": "cm" },
      "left": { "value": 2.2, "unit": "cm" },
      "right": { "value": 1.4, "unit": "cm" },
      "mirror": true
    }
  }
}

Com essa configuração, toda página ímpar tem uma margem de 2,2 cm à esquerda (a lombada) e de 1,4 cm à direita (o corte frontal); toda página par tem 1,4 cm à esquerda (o corte frontal) e 2,2 cm à direita (a lombada). Cada página diagramada traz sua própria contentArea no VDTPage, então tudo o que deriva dela (colunas, faixas de flutuantes na largura total, contêineres de cabeçalho e rodapé e faixas de abertura span: 'page') segue automaticamente a geometria espelhada. Os quadros de página e de sangria usados pelos elementos de design ancorados em 'page' / 'bleed' não são afetados: eles descrevem a folha física, não as margens.

#Encadernação

“Documentos em chinês compostos na vertical são encadernados do lado direito, e os compostos na horizontal, do lado esquerdo” (clreq §7.1.1.1). page.binding: 'right' diagrama um livro para a borda direita:

• A página 1 continua ímpar e continua sendo o recto, então breakBefore.parity, :::pagebreak{parity}, os elementos de design com parity e toda contagem de páginas mantêm o sentido. O que muda é o lado em que fica o recto: a página da esquerda da página dupla. Um capítulo que abre num novo recto abre numa página da esquerda (clreq §7.1.3.3).
• Com margins.mirror, left continua sendo a margem interna, mas são as páginas ímpares que trocam: a página 1 tem a margem interna à direita, a página 2 à esquerda. Uma coluna lateral oneAndHalf em 'outer' / 'inner', um flutuante girado que encosta na lombada, as margens das páginas de parte e os ícones de canto dos boxes em 'outer' / 'inner' seguem a mesma regra.
• O documento informa isso (VDTDocument.binding: 'right'), então um host nunca precisa ler a configuração: o Sandbox mostra suas páginas duplas como [3 | 2], com a página 1 sozinha à esquerda da lombada, e o visualizador HTML dele avança as páginas da direita para a esquerda, abrindo na ponta direita, com a seta da esquerda indo para a página seguinte. renderToHtml no modo múltiplo dispõe a fileira da direita para a esquerda.
• O PDF traz /ViewerPreferences << /Direction /R2L >> e /PageLayout /TwoPageRight (a página 1 sozinha, depois em pares), marcado ou não. O Acrobat e o Foxit seguem essas indicações; o leitor embutido do Chrome ignora as duas.

Fólios e cabeços não mudam de lugar sozinhos: um modelo que imprime o número da página no canto externo precisa ter seus elementos de páginas ímpares e pares ajustados para a borda direita (os elementos aceitam parity).

Um livro escrito da direita para a esquerda (árabe, persa, hebraico…) também é encadernado à direita: 'auto' dá a borda direita quando a direction do documento resulta em 'rtl'. Um livro assim também espelha todo o fluxo, de modo que sua primeira coluna é a da direita, e os recuos, os marcadores de lista, os flutuantes e as notas ficam à direita; os espaços de cabeçalho e rodapé continuam físicos. Veja Composição árabe.

Uma HQ lida da direita para a esquerda também é encadernada à direita: 'auto' dá a borda direita quando a configuração tem uma seção comics cujo sentido de leitura resulta em 'rtl'. É o caso de um mangá (comics.artDirection: 'rtl') e de uma edição em japonês ou em chinês tradicional de uma HQ ocidental. Quem decide é a seção, para o livro inteiro, e não os blocos :::page de um capítulo. Veja Quadrinhos.

#Predefinições de tamanho de página

Os quatro formatos de jornal são novos no postext 1.18 e ficaram fora do desenho: uma página standard tem quase quatro vezes a área de uma de 21 × 28. Costumam ser compostos com o layout 'multiple'; seis colunas são comuns num standard, e cinco num tabloide.

#Grade de linhas de base

A grade de linhas de base é o ritmo do texto corrido: linhas separadas por uma entrelinha do corpo, contadas a partir do topo da área de conteúdo. A diagramação a usa quer ela seja desenhada, quer não: títulos, fins de lista, boxes, figuras e fórmulas destacadas devolvem o texto à grade (a menos que o próprio snapToGrid deles esteja desligado), e assim as linhas de colunas vizinhas continuam alinhadas. enabled só desenha as linhas, no canvas, no PDF e nas visualizações do Sandbox, para conferir esse ritmo; ligá-lo ou desligá-lo não move nada. As linhas cobrem apenas o texto real da página (da primeira linha de texto à última), então faixas de flutuantes, páginas em branco de paridade e o espaço vazio no fim não mostram grade.

page: {
  baselineGrid: { enabled: true, color: { hex: '#e0e0e0', model: 'hex' } }
}

#Marcas de corte

Quando ativadas, o canvas cresce para incluir uma área de sangria, e o motor desenha marcas de corte em cada canto para a produção gráfica. O PDF dá a cada página uma TrimBox e uma BleedBox; um arquivo PDF/X as tem mesmo sem marcas de corte. No Sandbox, elas são definidas em Exportação › Preparação para impressão.

A folha cresce bleed + markOffset + markLength em cada lado, e a página refilada fica no meio dela. Cada canto do refile recebe duas marcas de comprimento markLength, cada uma alinhada com uma das bordas que se encontram ali. Uma marca começa markOffset fora do refile, ou na borda da sangria quando bleed é o maior dos dois, para que nenhuma marca fique sobre arte que entra na sangria. Com os padrões (3 mm de sangria, 3 mm de afastamento), as marcas vão de 3 a 8 mm fora do refile, e uma faixa em branco de 3 mm de largura contorna a folha por fora delas. cropMarkSegments(page, doc.config.page, doc.trimOffset) devolve as oito marcas de uma página em pixels da página, as mesmas que os renderizadores canvas e PDF desenham. O terceiro argumento é a posição do refile dentro da folha, o valor a partir do qual o TrimBox do PDF é escrito; se omitido, é calculado a partir de cutLines da mesma forma.

Nada além das marcas é impresso fora da sangria. Tudo o que a página pinta, incluindo os elementos de design ancorados em 'page' ou 'bleed', é recortado na caixa de sangria no canvas, no PDF e na saída HTML, como faz uma exportação de DTP: uma faixa ou uma imagem colocada de propósito além da sangria é cortada na borda da sangria, onde o refile a perderia de qualquer forma. Até o postext 1.4, um elemento assim passava por cima das marcas até a borda da folha.

No PDF (postext-pdf), a MediaBox de cada página é a folha inteira. A página também traz uma TrimBox, a página refilada, e uma BleedBox, o refile mais a sangria, que as ferramentas de imposição e de preflight leem. As marcas são pintadas em cor de registro, a separação /All, e por isso saem em todas as chapas. Isso vale qualquer que seja o espaço de cor em que o PDF é escrito (RGB, escala de cinza ou CMYK): um preto comum chegaria à gráfica como preto composto ou apenas na chapa do preto. color só se aplica ao canvas.

#Numeração

O bloco page.pageNumbering controla como os rótulos de página são formatados e onde o contador começa. Ele define apenas o padrão do documento inteiro; para reiniciar a numeração no meio do documento (por exemplo, elementos pré-textuais em algarismos romanos passando a capítulos em decimais a partir de 1), use a diretiva :::numbering (veja Formato do documento → Diretivas).

O rótulo calculado fica guardado em cada VDTPage como pageLabel e é o valor em que o marcador {pageNumber} de cabeçalho e rodapé se resolve. Os PDFs emitem uma árvore numérica /PageLabels, para que o indicador de página e a navegação “Ir para a página” do Preview e do Acrobat correspondam exatamente aos rótulos impressos. Um estilo para o qual o PDF não tem código (numerais chineses, algarismos circulados e de largura total) é escrito página por página, e assim o leitor também mostra 一, 二, 三.

Grafias dos formatos de numeração

Três ajustes escolhem um formato de numeração, e cada um ganhou a sua própria grafia: os rótulos de página (page.pageNumbering.format e :::numbering{format=…}) dizem lower-roman, as listas numeradas (orderedLists.numberFormat) dizem arabic para decimal, e os tipos de recurso (counterFormat) dizem roman-lower. Todos aceitam todas as grafias abaixo, então um formato copiado de um ajuste funciona nos outros. Os nomes não diferenciam maiúsculas de minúsculas; as formas de um caractere, sim (i e I são diferentes).

Os estilos do Leste Asiático mantêm seus nomes de CSS Counter Styles nos três ajustes. Os numerais chineses informais escrevem 十 de 10 a 19 sem um 一 à frente (十二, mas 一百一十), um único 零 para uma sequência de zeros dentro do número (一百零一, 一千零五十), e 万 ou 萬 para dez mil, 亿 ou 億 para cem milhões (一万零一十). Só cjk-decimal usa 〇, algarismo por algarismo, como se escrevem os anos (二〇二六, GB/T 15835—2011). Os troncos param em 10, os ramos em 12 e os algarismos circulados em 50; além disso, o número sai em algarismos. 一 e 壹 seguem a escrita do locale do documento: tradicional para zh-Hant, zh-TW ou zh-HK, simplificada nos outros casos. Algumas edições antigas escrevem 101 como 一百一, sem 零; o Postext não imprime essa forma.

Os estilos japoneses (desde o postext 1.16) também seguem as CSS Counter Styles. japanese-informal escreve 十 sem um 一 à frente e sem 零 para uma casa vazia (百一, 千十), e japanese-formal os 大字 壱 弐 参 拾 百 阡, com 壱 mantido antes de cada unidade (壱拾, 壱百). O CSS para os dois em 9.999; o Postext continua em grupos de quatro algarismos com 万 億 兆 (no formal, 萬 億 兆), e cada grupo mantém seu 一 antes de uma unidade: 一万一 é 10.001, 一億一万 é 100.010.000. Num documento em japonês (ja, ja-JP…), 一 significa japanese-informal, então 第{1:一}章 imprime 第百一章 ali e 第一百零一章 num documento em chinês; 壹 continua sendo os numerais formais chineses. As séries de kana são as listas do CSS: 48 kana na ordem gojūon (incluindo ゐ e ゑ) e 47 na ordem do poema iroha; depois do último, continuam com dois kana (ああ, いい), e não têm zero, então um item numerado 0 imprime 0. Os algarismos kanji posicionais (二〇二六), a forma dos anos e dos fólios, são cjk-decimal.

Os estilos árabes mantêm o nome do CSS quando o CSS tem um (arabic-indic, persian; urdu e maghrebi-abjad, das Ready-made Counter Styles do W3C, são lidos como persian e arabic-abjad-maghrebi). arabic mantém o sentido antigo, os algarismos europeus. arabic-abjad escreve os numerais abjad aditivos do árabe clássico e da foliação de manuscritos, do valor mais alto para o mais baixo: 11 é يا, 1.446 é غتمو, e a contagem dos milhares vem antes de غ (2.000 بغ, 1.002 غب); acima de 999.999, o número sai em algarismos. A nota do W3C usa esse nome para uma série de 28 letras em que 11 é ك; o Postext chama essa série de abjad, a numeração por letras dos itens de lista na ordem abjad (أ، ب، ج، د، هـ), e de hijai a ordem alfabética (أ، ب، ت، ث). As duas escrevem a primeira letra com sua hamza (أ), e um heh que ficaria isolado como هـ, com um tatweel, para que nenhuma seja lida como os algarismos ١ e ٥; depois de 28, elas dobram, como faz lower-alpha (أأ, أب). Os valores magrebinos seguem o mnemônico صعفض قرست ثخذ ظغش (ص 60, ض 90); a lista do W3C troca ص e ض. Um único أ não distingue as duas séries de letras, então seus tokens são as quatro primeiras letras de cada uma: {1:أبجد}, {1:أبتث}. Os algarismos do próprio documento são definidos com numerals.

As outras grafias servem para configurações que ninguém verifica por tipo: predefinições em JSON e JavaScript puro. Os tipos do TypeScript continuam nomeando só a grafia própria de cada ajuste (a que o Sandbox escreve e resolveAllConfig devolve, incluindo os nomes do Leste Asiático), então um PostextConfig tipado fica nela, e outra grafia exige um cast.

// JavaScript ou uma predefinição JSON (em TypeScript, a grafia própria de cada ajuste)
orderedLists: { numberFormat: 'decimal' },          // igual a 'arabic'
page: { pageNumbering: { format: 'roman-lower' } }, // igual a 'lower-roman'
resourceTypes: [{ id: 'plate', counterFormat: 'upper-roman', … }], // igual a 'roman-upper'

resolveAllConfig converte os formatos de lista e de página para a grafia do próprio ajuste ('decimal' vira 'arabic' em orderedLists, 'roman-lower' vira 'lower-roman' em page.pageNumbering), e stripConfigDefaults descarta uma grafia do valor padrão. Os painéis do Sandbox mostram cada um dos três ajustes na sua própria grafia, qualquer que seja a usada na configuração. Qualquer outro valor (roman, 01, um erro de digitação) numera em decimal em vez de imprimir undefined, e é informado como um aviso de configuração. Os modelos de numeração de títulos aceitam os mesmos nomes depois dos dois-pontos ({1:roman-upper} é {1:I}), ao lado do seu próprio {1:01} com zeros à esquerda.

#Diagramação

A propriedade layout controla como as colunas se dispõem dentro da área de conteúdo.

#Escrita vertical

Com writingMode: 'vertical-rl', uma página é diagramada como uma página horizontal girada um quarto de volta no sentido horário. O fluxo é composto num quadro tão largo quanto a folha é alta; as linhas dele são as colunas do texto vertical, lidas a partir da direita, e tudo o que o motor faz com linhas (quebra, justificação, flutuantes, notas de rodapé, regras de manter junto) funciona nesse quadro. Assim, na folha:

• Uma coluna do layout é um andar (栏): layoutType: 'double' dá dois andares empilhados de cima para baixo, preenchidos a partir do canto superior direito; gutterWidth é o vão entre eles, e o fio entre colunas, um fio horizontal entre eles. Os andares não são equilibrados no fim de um capítulo (clreq §7.1.3.4): o equilíbrio de colunas fica desligado num documento vertical, a menos que headings.balancing.enabled esteja definido.
• O que o fluxo chama de “topo” é a borda direita da folha, onde a leitura começa: um flutuante no topo fica à direita da página, um no pé à esquerda, uma abertura na largura da página é uma faixa descendo pela borda direita, e as notas de rodapé caem na ponta esquerda de cada andar. Um elemento de design ancorado no topo da página (o design de um título, um boxe fixo) é ancorado na borda direita. sideColumnSide 'left' é o andar de cima, 'right' o de baixo; 'outer' e 'inner' são lidos como 'right' e 'left'.
• As margens do fluxo são as margens da folha giradas: a margem direita é o topo do fluxo, e a margem superior, a sua esquerda. page.margins mantêm seus nomes na folha.
• Cabeços, fólios, marcas de corte e o fundo da página ficam na folha, compostos na horizontal, como o clreq descreve para livros verticais.
• Figuras e tabelas ficam em pé. Uma figura ocupa a altura do seu andar até onde a legenda permite, no máximo com a largura da página; a largura que ela toma é o espaço que usa no fluxo. A legenda é composta na horizontal abaixo dela, assim como as células de uma tabela: as duas são medidas como texto horizontal. Uma tabela é composta em pé atravessando a página, com as linhas cortadas no andar quando é mais alta que ele. placement.align coloca uma figura no topo ('left'), no meio ou no pé do seu andar. Um placement.rotate não é aplicado onde a figura é citada pela primeira vez em texto vertical: o build informa um aviso de conteúdo rotateIgnoredVertical. Uma seção horizontal do livro (um estilo de título cujo layout define 'horizontal-tb') gira suas figuras como pedido.
• A imagem de um design (a ilustração de uma abertura, a de uma página de parte) também fica em pé. A caixa dela no fluxo é dimensionada com a largura e a altura da imagem trocadas, então size.width é quanto a imagem desce pela coluna, e sua largura na folha decorre das proporções.
• Caracteres: Han, kana e formas de largura total ficam em pé, um em cada; palavras latinas e números são girados de lado, com suas larguras horizontais; a pontuação usa a forma vertical da fonte. Os sinais de pausa e de ponto nunca são girados: uma fonte da China continental coloca 、。，． no canto superior direito da célula e ！？：； na metade direita dela, e uma fonte de Taiwan ou de Hong Kong os centraliza (cjk.region). Os parênteses e colchetes usam suas formas verticais, e “ ” ‘ ’ em texto continental são lidos como 『』「」. Travessões, reticências e o til ondulado usam a forma vertical da fonte quando ela existe (a Noto CJK associa a de — a vert junto com fwid: um fio descendo pelo meio da célula); caso contrário, são girados com a tinta centrada no eixo da coluna. Um 破折号 (——) em texto chinês é um único fio descendo pela coluna: suas formas verticais deixariam um branco nas duas pontas de cada célula, então cada travessão é girado com a linha e esticado como no texto horizontal (veja Larguras da pontuação). Um número de no máximo dois algarismos fica em pé numa única célula, a menos que esteja numa frase latina, cujas palavras ele acompanha (veja Números no texto vertical). O ponto mediano (·) ocupa meia célula em texto continental e uma célula inteira em texto de Taiwan e de Hong Kong. Os sinais que o Unicode define em pé (× © ± § ℃ ① e similares) ficam numa célula própria, também dentro de um número: 3×4 é 3 e 4 de lado, com × em pé entre eles. Um apóstrofo ou um ponto mediano entre duas letras de uma palavra latina (don’t, l·l) fica na palavra, de lado. Um parágrafo latino num fluxo vertical segue as mesmas regras. Fórmulas inline, chips e amostras de cor são girados de lado com a linha.
• Cada caractere é medido como é pintado: uma célula avança a sua célula linha abaixo, um trecho de lado a sua largura horizontal. O texto que fica na horizontal na folha (cabeços, fólios, legendas, células de tabela) é medido na horizontal.
• As larguras da pontuação, a pontuação pendurada e o espaço entre Han e latino valem ao longo da linha vertical como valem na horizontal. O branco antes de um glifo fica acima dele, e o branco depois, abaixo: um 、 Kaiming ocupa meia célula, 」「 se comprimem em uma célula e meia, um parêntese de abertura aparado no início de uma linha começa meia célula mais acima, um 。 pendurado fica abaixo do pé da sua linha, e o espaço Han–latino é um quarto de em da coluna acima e abaixo de uma palavra de lado. ：；？！ mantêm uma célula inteira no texto vertical em todas as regiões.
• A grade de caracteres conta caracteres ao longo da linha e linhas através da página: charsPerLine define o comprimento de um andar, linesPerPage quantas linhas cabem numa página, e layoutType: 'double' dá dois andares de caracteres inteiros com uma medianiz de ems inteiros entre eles.

Para hosts que leem a diagramação: uma página vertical traz VDTPage.flow. A contentArea, as colunas, os blocos, as linhas, os flutuantes, as áreas de notas de rodapé, a faixa de abertura e as sobreposições de design de bloco dela estão em coordenadas do fluxo; width, height, header e footer estão na folha. flowToPage, pageToFlow, flowRectToPage e pageRectToFlow convertem entre os dois, e verticalOrientation(char, region) diz como um caractere fica. flow.centralBaselines dá, por família tipográfica, o eixo em que a diagramação centralizou os caracteres em pé: o centro da tinta de 中, cujo traço longo ocupa a altura da caixa do em (0,38 em acima da linha de base na Noto Serif e na Noto Sans, SC e TC igualmente), e que toda fonte chinesa, japonesa e coreana tem. Cada linha é centralizada nesse eixo: a linha de base de uma linha vertical fica meia entrelinha mais a linha de base central da família abaixo do topo da caixa da linha (a de uma linha horizontal fica a 0,8 da entrelinha para baixo), de modo que uma coluna de caracteres fica no meio do seu passo, e um fio desenhado entre duas colunas a um passo inteiro cai a meio caminho entre elas. Um texto de design vertical é composto do mesmo modo, nas suas próprias linhas. O canvas pinta ele mesmo uma página vertical; para pintar a pontuação com as formas verticais da própria fonte, um host no navegador carrega, uma vez por família, uma fonte gêmea com elas ativadas: loadVerticalAlternates(family, faces), em que faces são as fontes da família (URLs ou bytes) e seus descritores. A gêmea só é mantida quando o navegador aplica o recurso ao texto do canvas (Chrome 140 e posteriores): ele desenha 「（《 com a gêmea e com uma cópia das mesmas fontes carregada sem o recurso, no peso e no estilo das fontes dadas, e mantém a gêmea quando a tinta das duas difere. Uma chamada posterior para outras fontes de uma família cuja gêmea está em uso (o negrito depois do regular) as acrescenta a ela. O Sandbox faz isso para toda família de um documento vertical. Sem uma gêmea, os parênteses são girados em torno da caixa do em, e os sinais de pausa e de ponto continentais são movidos dentro da célula para onde as formas verticais da fonte os colocam: 、。，． para o canto superior direito (a até 0,07 em das formas verticais da Noto Serif SC), ！？：； meio em para a direita e um pouco para cima (a até 0,02 em). O PDF e o HTML compõem a mesma página: veja Texto vertical no PDF e a tabela em Como a saída HTML difere do canvas e do PDF. Conferido célula por célula com o HarfBuzz (layout vertical com vert) na Noto Serif TC e SC, todo caractere de 「賈雨村」云云，宜乎？故曰！；：、。“引”‘單’…… fica a até 0,02 em dele no canvas e no PDF, e a até 0,05 em no HTML (o Chrome centraliza um glifo girado no meio entre o ascendente e o descendente da fonte, que na Noto fica 0,05 em acima do centro da caixa do em). flow.dashAdvances dá, por família, o avanço horizontal em ems de cada travessão que a página estica para preencher a célula (— – ― ⸺ ⸻ －), para um renderizador sem métricas de fonte próprias: o HTML estica o travessão com ele, como o canvas e o PDF fazem a partir das suas. Cabeços e fólios também podem ser compostos na vertical: veja Elementos de texto vertical.

#Fio entre colunas

Desenha uma linha vertical fina na medianiz para separar visualmente as colunas.

Abaixo de um título na largura da página (span: 'page'), o fio começa onde começa o texto das colunas, sob a faixa do título, seja a faixa pintada pela abertura padrão, seja por um design próprio. Até o postext 1.4, ele corria desde o topo do bloco de texto, atravessando a faixa.

Um estilo de título pode definir um fio próprio no seu layout (veja Estilos de título), e as páginas da sua seção desenham esse fio. Um campo que o estilo deixa sem definir assume o valor do documento, então uma seção que só muda as colunas mantém o fio do documento. Até o postext 1.4, o fio de um estilo nunca era desenhado: toda página desenhava o do documento.

#Tipos de layout

• 'single': uma coluna que ocupa toda a largura do conteúdo. Funciona melhor em páginas estreitas ou em textos densos, de parágrafos longos.

• 'double': duas colunas de mesma largura. É o layout editorial clássico, que mantém a medida da linha na faixa ideal de 40 a 50 caracteres para uma leitura confortável.

• 'oneAndHalf': um layout assimétrico, com uma coluna principal e uma coluna lateral mais estreita. A coluna lateral (controlada por sideColumnPercent) é ideal para notas de margem, figuras pequenas ou conteúdo de apoio. Valores entre 25 % e 40 % funcionam bem, e um canal estreito para números de linha ou marcas marginais fica em torno de 10 % a 15 %. A coluna lateral ocupa sideColumnPercent % da largura do conteúdo, e a coluna principal fica com o que sobra depois da medianiz; assim, com 50 % a coluna lateral é uma medianiz mais larga que a principal. Qualquer valor é diagramado como foi escrito enquanto as duas colunas mantiverem pelo menos 1 % da largura do conteúdo; um valor que deixaria uma delas mais estreita (0 ou menos, ou um valor tão grande que a coluna principal some atrás da medianiz) é limitado ao valor mais próximo que preserve as duas, e um valor que não é número assume o padrão, 33. Nesse caso, os configWarnings do documento trazem { kind: 'sideColumnPercentClamped', path: 'layout.sideColumnPercent', value, used } (o caminho do layout próprio de um estilo de título nomeia o estilo, como em headingStyles[2].layout.sideColumnPercent, e é medido nas margens desse estilo), que o Sandbox lista no painel Verificações; collectConfigWarnings(config) devolve a mesma lista sem diagramar nada. Um layout que não seja 'oneAndHalf' nunca lê o valor e nunca o reporta. Com sideColumnRole: 'floats', o texto corrido nunca entra na coluna lateral: ela vira um canal para as figuras, tabelas e boxes posicionados com span: 'side'. Uma figura ou tabela lateral se empilha a partir do topo do canal na página que a cita primeiro (a figura marginal de um livro didático fica no alto da página mesmo quando o texto a cita mais abaixo); a que não cabe no restante do canal espera o canal da página seguinte. Um boxe lateral se empilha ao lado do texto que interrompe e, quando o restante do canal não o comporta ali, sobe até a posição mais baixa em que ainda cabe (com o pé no pé do canal) ou espera a página seguinte. Quando o texto depois do fechamento do boxe continua na página seguinte (a coluna está cheia, ou as regras de quebra levam esse texto adiante), o boxe fica no seu fechamento, ao lado do texto anterior; um estilo com sideAtColumnEnd: 'after' o alinha, em vez disso, com a primeira linha do texto depois do fechamento, no canal da página seguinte, como pedem os números de linha e os títulos marginais escritos antes da linha a que se referem. Um elemento do design de um título que fica no canal (um numeral de capítulo ancorado na margem externa) também é mantido fora da pilha (veja Altura reservada). Flutuantes e boxes com span: 'page' continuam atravessando as duas colunas, e um flutuante de coluna com placement.captionSide põe a legenda no canal, alinhada com a figura. Combinado com margens espelhadas e sideColumnSide: 'outer', o canal fica na borda externa de todas as páginas: a coluna marginal de um livro didático.

• 'multiple': de três a oito colunas iguais, tantas quantas indicar columnCount (padrão 3): a grade dos jornais e de muitas revistas (desde o postext 1.18). Cada coluna tem (content width − (n − 1) × gutterWidth) / n de largura. O texto passa de uma coluna para a seguinte como em um layout de duas colunas; o fio de coluna é desenhado em todas as medianizes, o balanceamento de colunas nivela todas as colunas na página que fecha um capítulo e antes de um boxe da largura da página, as notas de rodapé funcionam em todas as colunas, e figuras, boxes e títulos da largura da página atravessam a página inteira. Uma figura ou um boxe flutuante pode ocupar só algumas colunas: placement.columns (veja Tipos de recurso) e o columns de um estilo de boxe. Um columnCount fora de 3 a 8, ou que não seja inteiro, é arredondado e limitado à contagem válida mais próxima (um valor que não é número assume 3), e os configWarnings do documento trazem { kind: 'columnCountClamped', path: 'layout.columnCount', value, used } (o caminho do layout próprio de um estilo de título nomeia o estilo, como em headingStyles[1].layout.columnCount). Um layout de outro tipo nunca lê o valor. Um estilo de título cujo layout é 'multiple' usa o columnCount do documento, a menos que defina o seu, de modo que um jornal composto em cinco colunas pode rodar as páginas de opinião em quatro.

#Cabeços e rodapés

As propriedades header e footer controlam os espaços de cabeçalho e de rodapé de cada página. Cabeços e rodapés são desenhados dentro das margens já existentes da página: não reservam espaço adicional nem reduzem a área de conteúdo.

Quadro do contêiner. Um elemento ancorado em 'container' é posicionado na faixa de margem entre o corpo e a borda de refile, com a largura da área de conteúdo. O contêiner do cabeçalho vai do refile superior até o topo do corpo; o do rodapé, da base do corpo até o refile inferior. Assim, as âncoras top-* do cabeçalho e bottom-* do rodapé são medidas a partir da borda de refile, enquanto as âncoras bottom-* do cabeçalho e top-* do rodapé são medidas a partir da borda do corpo. O contêiner nunca inclui a sangria nem a faixa das marcas de corte, então um cabeçalho ou rodapé fica na mesma posição na página refilada com page.cutLines ativado ou desativado. Ancore em 'page' (a caixa de refile) ou em 'bleed' para ir além da largura da área de conteúdo ou chegar à sangria.

Os espaços usam o modelo unificado de espaço de design: todo elemento tem um placement com uma anchor (no contêiner ou em outro elemento, por #id), um offset opcional e um size opcional. Os campos planos antigos align, marginFromBody, marginFromEdge e width: 'full' continuam aceitos na entrada e são migrados automaticamente para o novo formato; a descrição equivalente no novo formato está documentada abaixo.

Cada espaço contém uma lista de elementos de texto, fio e caixa. A ordem do array é a ordem de pintura (o primeiro elemento é pintado primeiro, o último fica por cima). Isso vale independentemente das âncoras: um elemento pode se ancorar em outro listado depois dele (anchor.to: '#ttl'), de modo que uma caixa de fundo pode vir primeiro e ainda assim ser posicionada em relação ao texto que fica sobre ela.

Padrões embutidos. Quando header ou footer é undefined, o postext aplica um padrão embutido razoável em vez de um espaço vazio:

• Cabeçalho padrão: {title} alinhado à direita nas páginas ímpares, {chapterTitle} alinhado à esquerda nas páginas pares e um fio de largura total, tudo na cor principal da paleta, Open Sans 8 pt/600, marginFromBody 16pt (texto) / 13pt (fio).
• Rodapé padrão: {pageNumber} centralizado em todas as páginas, na cor principal da paleta, Open Sans 8 pt/600, marginFromBody 16pt.

Para dispensar os padrões embutidos, defina header: { elements: [] } (ou footer: { elements: [] }). Um array elements vazio e explícito é preservado como “nenhum elemento”; só undefined aciona os padrões.

#Elementos de texto

Os elementos de texto desenham uma string de modelo com substituição de marcadores. Os marcadores usam a sintaxe {name}; {{ e }} produzem chaves literais.

Os padrões da tabela abaixo são os de um elemento de texto que você mesmo adiciona. O cabeçalho e o rodapé embutidos descritos em Padrões embutidos, acima, são elementos prontos com valores próprios (Open Sans 8 pt/600 na cor principal da paleta), não os padrões do elemento.

Marcadores disponíveis:

• {pageNumber}: número da página atual, a partir de 1.
• {totalPages}: total de páginas do documento. Em um livro diagramado capítulo a capítulo (o Sandbox, buildBundle), cada capítulo é um documento, então este é o total do próprio capítulo.
• {bookTotalPages}: total de páginas do livro inteiro: todos os capítulos, páginas em branco incluídas. Para um documento diagramado sozinho, é igual a {totalPages}. Veja Contagem de páginas do livro abaixo.
• {title}, {subtitle}, {author}, {publishDate}: valores lidos de content.metadata. Metadados desconhecidos ou vazios viram uma string vazia (e geram um aviso no Sandbox).
• {chapterTitle}: texto do H1 mais recente na página atual ou antes dela. Um H1 cujo estilo de título define runningChapter: false (uma prancha, um mapa) é ignorado.
• {chapterTitleAtTop}, {chapterNumberAtTop}: título e número do capítulo vigente no topo da página, que diferem de {chapterTitle} e {chapterNumber} em uma página onde um novo capítulo começa abaixo de outro texto. Veja Capítulo no topo da página abaixo.
• {partTitle}, {partNumber}: título e número da parte atual (a página :::part mais recente na página atual ou antes dela; as páginas em branco de paridade logo antes de uma página de parte já pertencem a ela). Vazios antes da primeira parte.
• {firstMark.<key>}, {lastMark.<key>}: a primeira e a última palavra-guia da página: um título de um nível (h1–h6) ou uma entrada de um estilo de parágrafo. Veja Palavras-guia abaixo.

Contagem de páginas do livro

{bookTotalPages} imprime o número de páginas do livro inteiro, o total que o leitor vê em “página 12 de 348”. Conta páginas físicas, em branco incluídas, como {totalPages}, mas somando todos os capítulos:

• Um documento diagramado sozinho (buildDocument sem continuation) é o livro inteiro: {bookTotalPages} é igual a {totalPages}.
• buildBundle diagrama o livro, soma as páginas de todos os capítulos e diagrama mais uma vez com esse total, de modo que todos os capítulos imprimem o mesmo número. A contagem nunca move uma quebra de página, então uma rodada a mais resolve; uma configuração que não imprime {bookTotalPages} não paga nada por isso.
• O Sandbox passa o total a cada capítulo assim que as páginas de todos os capítulos são conhecidas. Até lá, um capítulo imprime as páginas até o seu próprio fim. A exportação do livro inteiro na aba PDF conta as páginas que diagrama: quando um capítulo imprimiu outro total, porque suas páginas ainda não eram conhecidas, ela diagrama o livro mais uma vez com o total a que os capítulos chegaram.
• Um host que diagrama os capítulos por conta própria passa o total como continuation.bookPageCount (também no primeiro capítulo). Sem isso, {bookTotalPages} conta as páginas até o fim do documento (continuation.pageIndexOffset mais as suas próprias páginas), o que só está certo no último capítulo.

footer: {
  elements: [{
    kind: 'text', id: 'folio', content: '{pageNumber} / {bookTotalPages}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'top' }, size: { width: 'auto', height: 'auto' } },
  }],
}

configUsesPlaceholder(config, 'bookTotalPages') diz a um host se vale a pena calcular a contagem.

Palavras-guia: primeira e última marca

Um dicionário imprime no cabeço a primeira e a última entrada de cada página (“Aback – Anchor”); uma obra de referência imprime a primeira e a última seção. {firstMark.<key>} e {lastMark.<key>} as imprimem. A chave indica o que marca uma página:

• h1 a h6: um título desse nível. A marca é o texto dele, sem o número.
• Um id de estilo de parágrafo (entry): um parágrafo de um contêiner :::paragraphs{style="entry"}. A marca é o trecho em negrito que abre o parágrafo, a palavra-entrada, sem a pontuação final: **Aback.** Said of… marca Aback. Um parágrafo que não começa com texto em negrito não define marca.

{firstMark.<key>} é a primeira marca que começa na página e {lastMark.<key>}, a última. Uma página em que nenhuma marca começa (uma entrada longa que continua) imprime nos dois a marca vigente, a última antes dela. As páginas anteriores à primeira marca não imprimem nada; em um livro diagramado capítulo a capítulo, isso vale para a primeira marca do capítulo, já que as marcas não passam de um capítulo para o seguinte. Um título ou parágrafo dividido entre páginas marca só a página em que começa. A chave é escrita depois do ponto com letras, dígitos, _ e -, começando por uma letra ou _; uma chave desconhecida não imprime nada.

:::paragraphs{style="entry"}
**Aback.** Said of the sails when pressed back against the mast.
 
**Abaft.** Towards the stern, or behind a given point.
:::

header: {
  elements: [{
    kind: 'text', id: 'guide', content: '{firstMark.entry} – {lastMark.entry}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom' }, size: { width: 'auto', height: 'auto' } },
  }],
}

As palavras-guia são cabeços: são resolvidas nos espaços de cabeçalho e de rodapé (incluídos o header e o footer de um estilo de título) e não imprimem nada em designs de título, de parte e de sumário; nos designs de título e de parte, o painel Verificações as aponta como marcadores desconhecidos. Para mostrar a primeira entrada nas páginas pares e a última nas ímpares, use dois elementos, com parity: 'even' e parity: 'odd'. Um H1 cujo estilo de título define runningChapter: false não define marca h1.

Capítulo no topo da página

{chapterTitle} e {chapterNumber} nomeiam o último capítulo iniciado na página ou antes dela. Em um livro cujos capítulos correm seguidos, sem quebra de página entre eles, uma página que fecha um capítulo e começa o seguinte perto do pé leva o título do novo capítulo sobre um texto que ainda pertence ao anterior. {chapterTitleAtTop} e {chapterNumberAtTop} nomeiam, em vez disso, o capítulo vigente no topo da página, como fazem os romances com capítulos seguidos e muitas obras de referência:

• uma página cujo primeiro bloco é o H1 de um capítulo nomeia esse capítulo;
• qualquer outra página nomeia o capítulo que continua nela, mesmo quando um novo capítulo começa mais abaixo;
• uma página em branco adicionada por paridade acompanha a página seguinte, e o separador dos modos always-*, a página anterior (veja Pertencimento das páginas em branco); quando a página depois de uma página em branco de paridade começa com o fim de um capítulo, e não com o H1 dele, a página em branco também fica com esse capítulo;
• um H1 com runningChapter: false é ignorado.

header: {
  elements: [{
    kind: 'text', id: 'chapter', content: '{chapterTitleAtTop}', parity: 'odd', pages: 'body',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom-right' }, size: { width: 'auto', height: 'auto' } },
  }],
}

Como as palavras-guia, os dois são cabeços: são resolvidos nos espaços de cabeçalho e de rodapé e não imprimem nada em designs de título, de parte e de sumário. {attr.<key>} sempre lê o último capítulo iniciado.

Alinhamento implícito pela borda

Quando o placement.anchor.to de um elemento de texto se refere a outro elemento por #id, a borda da âncora implica um alinhamento de texto padrão para as linhas quebradas:

• right-of e align-left implicam align: 'left' no texto: as linhas quebradas correm para a direita a partir da âncora.
• left-of e align-right implicam align: 'right': as linhas quebradas se apoiam no lado mais próximo do alvo da âncora.

O editor de títulos do Sandbox aplica esses alinhamentos implícitos automaticamente quando você muda a borda ou o alvo da âncora. Eles mantêm um texto quebrado em várias linhas visualmente ancorado no elemento a que se refere (assim, por exemplo, o “P” de um “Postext” quebrado fica alinhado na vertical sob o “I” de “Introduction”).

Marcas inline e contornos

Por padrão, um elemento de texto compõe o texto em uma só fonte: **, ^ e os demais sinais de Markdown são impressos como foram escritos. Com inlineMarks: true, o texto resolvido é lido como Markdown inline, com as mesmas marcas que o texto corrido aceita (veja Formato do documento → Formatação inline):

• **bold** aplica peso 700 (ou o fontWeight do próprio elemento, quando for mais pesado); *italic* inverte a inclinação do elemento, de modo que a ênfase dentro de um elemento em itálico sai em redondo; ***both*** faz as duas coisas. As formas com sublinhado (__bold__, _italic_) também funcionam.
• ^superscript^ e ~subscript~ são compostos a 58 % do tamanho, o sobrescrito elevado em um terço dele e o subscrito rebaixado em 0,15 dele; um subscrito e um sobrescrito que se tocam (T~0~^2^) são empilhados, como no corpo.
• Uma barra invertida compõe o próprio sinal (\*, \_, \^, \~). Um link mantém o texto; as crases de código são descartadas.

As marcas são lidas depois que os marcadores são preenchidos, então um valor pode trazê-las: a linha de autores em um atributo de título recebe os números de afiliação como sobrescritos. Quebra de linha, justificação, os modos de reticências, dropCap e paragraphIndent funcionam com texto marcado; todos os trechos mantêm a cor do elemento.

{ "kind": "text", "id": "authors", "content": "{attr.authors}", "inlineMarks": true, "overflow": "wrap",
  "fontSize": { "value": 11, "unit": "pt" },
  "placement": { "anchor": { "to": "#title", "edge": "below" }, "offset": { "y": { "value": 6, "unit": "pt" } } } }

# Snow cover and river flow {authors="Ana Ruiz^1^, Luis Gil^2^ and Marta Sanz^1,3^"}

stroke desenha um contorno em volta das letras: width é a espessura do traço, centrado nas bordas dos glifos (metade fica dentro das letras, metade fora; a largura medida do texto não muda), color tem como padrão a cor do texto, e hollow: true deixa as letras sem preenchimento, para que só o contorno apareça: um número de display vazado, um título que se destaca sobre uma fotografia. O contorno é pintado sobre o preenchimento, do mesmo jeito no canvas, no HTML (-webkit-text-stroke) e no PDF (modo de renderização de texto 2, ou 1 quando vazado).

{ "kind": "text", "id": "year", "content": "1863", "fontFamily": "Bitter", "fontSize": { "value": 120, "unit": "pt" }, "fontWeight": 700,
  "color": { "hex": "#1d3557", "model": "hex" },
  "stroke": { "width": { "value": 1.5, "unit": "pt" }, "hollow": true },
  "placement": { "anchor": { "to": "page", "edge": "bottom-right" }, "offset": { "x": { "value": -15, "unit": "mm" }, "y": { "value": -20, "unit": "mm" } } } }

No PDF, os trechos em negrito e itálico incorporam as fontes correspondentes da família do elemento, então o provedor de fontes precisa fornecê-las.

Valores padrão do texto e armadilhas da ancoragem

Um elemento de texto que você mesmo escreve parte destes valores, alguns deles surpreendentes:

• overflow é 'ellipsis-end'. Um texto largo demais para o espaço é cortado em uma linha com …. Defina overflow: 'wrap' para um endereço, uma linha de autoria ou qualquer título que possa ficar longo. Uma quebra de linha no conteúdo (uma quebra real, ou \n no modelo ou no valor de um atributo) começa uma nova linha em todos os modos; os modos de reticências cortam cada linha separadamente.
• align é 'center' e verticalAlign é 'middle'. Um elemento de largura automática se ajusta à sua linha mais longa, então as linhas ficam centralizadas umas em relação às outras; defina align: 'left' para um bloco alinhado à esquerda (um elemento de largura automática ancorado em outro elemento alinha as linhas sozinho pelo lado da âncora, veja acima).
• A fonte é EB Garamond 8 pt, preta, lineHeight 1.2, qualquer que seja a do texto corrido. Ao contrário das outras entrelinhas da configuração, a lineHeight de um texto de design costuma ser um múltiplo simples (1.2); uma Dimension também funciona (veja acima).

Um elemento sem placement.size.width (ou com 'auto') se dimensiona pelo seu texto, mas só dentro do espaço entre o ponto de âncora e a borda do contêiner para a qual ele cresce; para uma âncora top ou bottom, o dobro da distância até a borda mais próxima. O offset dele conta. Um deslocamento para longe dessa borda não custa nada: um cabeço ancorado em top-left com x negativo (pendurado na margem esquerda) não perde espaço, porque cresce para a direita. Um deslocamento em direção a essa borda reduz o espaço na mesma medida (o dobro, para uma âncora top ou bottom), e um que empurra a âncora além da borda não deixa espaço nenhum: uma âncora top-right cujo x fica abaixo de menos a largura do contêiner, ou uma âncora top deslocada para o lado em mais da metade dessa largura. Sem espaço, um modo de reticências não imprime nada e 'wrap' empilha um caractere por linha. Três saídas:

• dar ao elemento uma size.width fixa: larguras fixas nunca são limitadas;
• ancorá-lo em 'page' ou 'bleed', o que faz da página (ou da sangria) o quadro do seu espaço;
• ancorá-lo na borda oposta do contêiner.

O contêiner de um cabeçalho vai do refile superior até o corpo, e o de um rodapé, do corpo até o refile inferior: no cabeçalho, as âncoras top-* são medidas a partir da borda de refile e as bottom-* a partir do corpo, e o contrário no rodapé (veja Quadro do contêiner, acima). Um cabeçalho ou rodapé nunca desloca o texto corrido e é pintado por cima dele, então um elemento empurrado para a área do corpo cobre o texto. Já uma faixa de abertura é pintada por baixo do texto corrido; quanto espaço ela ocupa no fluxo está descrito em Altura reservada.

#Elementos de texto verticais

Um elemento de texto com writingMode: 'vertical-rl' é composto na vertical em um espaço cujo texto é horizontal: os cabeços e fólios de qualquer livro, que ficam na folha, e todos os designs de uma página horizontal. Ele é diagramado como um texto horizontal em um quadro próprio girado um quarto de volta no sentido horário e depois girado de volta para a página:

• A caixa dele fica onde o posicionamento a coloca. A altura é o comprimento de uma linha: size.height a define (ou 'auto', o comprimento do texto; 'fill', até a borda do contêiner), size.width define quantas linhas cabem na largura, e size.maxWidth limita o comprimento de uma linha.
• align posiciona as linhas ao longo da caixa ('left' em cima), verticalAlign no sentido transversal ('top' à direita, onde fica a primeira linha), e o padding de uma caixa fica no lado para o qual foi escrito.
• Os caracteres são medidos e pintados como em uma página vertical: os Han em pé, um em cada, a pontuação na sua forma vertical, as palavras latinas deitadas, os números curtos em uma célula (cjk.uprightDigits). O canvas, o PDF e o HTML o colocam no mesmo retângulo.
• Com inlineMarks: true, as marcas de orientação destacam um trecho como no corpo: 第:tcy[3.0]回 compõe 3.0 em uma célula, :upright[GDP] põe as letras em pé, uma sob a outra, :sideways[…] gira um trecho; uma linha nunca quebra dentro de um deles. Um elemento horizontal os ignora.
• Um elemento vertical não leva capitular.
• No fluxo de uma página vertical (uma abertura, uma página de parte, o título de um boxe) o texto já corre para baixo, e writingMode não muda nada ali.

Os livros chineses verticais põem cabeços e fólios em um de três lugares (clreq §7.2; JLREQ §2.6 para o japonês):

Os cabeços na margem externa, como o Sandbox os adiciona (Cabeçalho › Cabeços na margem externa (vertical)), aqui para um corpo de 10 pt (o Sandbox os compõe a 80 % do tamanho do corpo):

{
  "page": { "pageNumbering": { "format": "trad-chinese-informal" } },
  "header": { "elements": [
    { "kind": "text", "id": "head", "content": "{chapterTitle}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "top" }, "offset": { "y": { "value": 4, "unit": "em" } } } },
    { "kind": "text", "id": "folio", "content": "{pageNumber}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "bottom" }, "offset": { "y": { "value": -5, "unit": "em" } } } }
  ] }
}

anchor.to: 'outer' (veja Posicionamento de elementos) é a margem externa de cada página, então os dois elementos descem pela borda esquerda de uma página ímpar e pela borda direita de uma página par em um livro com encadernação à direita (page.binding). {pageNumber} é impresso no formato de numeração de páginas: trad-chinese-informal dá 一百零三 na página 103, cjk-decimal dá 一〇三. As regras de cada espaço continuam valendo: pages: 'body' mantém o cabeço fora das aberturas de capítulo. Um pequeno ornamento entre o cabeço e o fólio (um rabo de peixe ︻, um fio) é um elemento comum ancorado no mesmo quadro.

Na VDT, um bloco vertical traz vertical (VDTDesignTextBlock.vertical: a região, os dígitos em pé e o eixo central de cada família); as linhas dele ficam no quadro girado do próprio bloco, xOffset para baixo a partir do topo da caixa, baselineY para a esquerda a partir da borda direita. Um trecho de uma linha marcada traz tcy ou orientation, como um segmento do corpo.

#Elementos de fio

Os elementos de fio desenham uma linha: horizontal, atravessando o espaço, ou vertical, descendo por ele.

#Elementos de caixa

Os elementos de caixa pintam um retângulo de cantos arredondados dentro do espaço, úteis como fundo atrás do texto em aberturas de capítulo, barras laterais ou rodapés. Os elementos de caixa são posicionados exclusivamente pelo campo placement; não têm a forma abreviada plana antiga. Preenchimento, traço e raio dos cantos ficam no objeto aninhado style (ElementBoxStyle), como no exemplo JSON em “Posicionamento de elementos”.

#Elementos de imagem

Um elemento image desenha um recurso bitmap ou SVG do documento: o logotipo da editora em uma folha de rosto, uma marca em um cabeço. Ele é dimensionado pelo seu placement.size: com um de width / height em 'auto' (o padrão), o outro lado acompanha a proporção da imagem; com os dois definidos, a imagem é ajustada dentro da caixa e centralizada. Um recurso ausente, ou que não seja imagem, não desenha nada.

{
  kind: 'image', id: 'logo', resourceId: 'logo-publisher',
  placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}

resourceId aceita os mesmos marcadores que o content de um elemento de texto, de modo que um único design pode desenhar uma imagem diferente para cada título. Com resourceId: '{attr.vignette}' em um estilo de título, # Chapter I {style="opener" vignette="log"} desenha o recurso log e # Chapter II {style="opener" vignette="wig"} desenha wig: os capítulos compartilham o estilo em vez de terem um clone por imagem. Um cabeçalho ou rodapé lê os atributos do capítulo da página, como faz {attr.<key>} em um cabeço, e outros marcadores também funcionam ('map-{chapterNumber}'). Um id que resulta vazio, como o de um título sem o atributo, não desenha nada. Desde o postext 1.8.

O renderizador de PDF incorpora o recurso como uma figura (um SVG com matriz de impressão usa a matriz); o visualizador HTML o resolve por meio de resourceImageUrl.

Uma imagem desenhada por um design é conteúdo quando o recurso dela a descreve: o altText do recurso ou, na falta dele, a legenda como texto simples (um chip lido pelo rótulo, um :ref pelo seu text, quando tem um) vai para a VDT (VDTDesignImageBlock.altText), vira o alt do <img> no HTML e uma Figure com /Alt em um PDF etiquetado, lida logo depois do texto do seu design (a prancha de um capítulo depois do título do capítulo). Uma imagem cujo recurso não tem nenhum dos dois, e uma marcada como decorative, é decoração: alt="" com role="presentation", e um artefato no PDF. A imagem de um cabeço ou de um rodapé se repete em todas as páginas, então é elemento fixo da página, diga o recurso o que disser: sem altText na VDT, alt="" com role="presentation" no HTML, um artefato da página no PDF.

#Posicionamento de elementos

ElementPlacement é o modelo unificado de posicionamento usado por todos os tipos de elemento (texto, fio, caixa) dentro de qualquer espaço de design: cabeçalho da página, rodapé da página ou o espaço de design avançado de um nível de título. Três informações descrevem um posicionamento:

interface ElementPlacement {
  /** What this element anchors to and which edge of that target. */
  anchor: {
    to: 'container' | 'page' | 'bleed' | 'outer' | `#${string}`; // container = the slot; page = trim box; bleed = trim box + bleed; outer = the outer margin (header, footer); #id = another element
    edge: AnchorEdge;
  };
  /** Distance from the anchor point. */
  offset?: { x?: Dimension; y?: Dimension };
  /** Optional fixed width / height. Width also accepts 'fill' (span the slot).
   *  `maxWidth` caps an 'auto' width (text): the element still shrink-wraps its
   *  content, so elements anchored to it stay attached, but a long text wraps or
   *  ellipsizes there — a running head can reserve room for the label hanging
   *  off it instead of squeezing that label out. */
  size?: { width?: Dimension | 'fill' | 'auto'; height?: Dimension | 'fill' | 'auto'; maxWidth?: Dimension };
}

AnchorEdge aceita:

• Bordas do contêiner (quando anchor.to é 'container', 'page' ou 'bleed'): top, top-left, top-right, bottom, bottom-left, bottom-right, left, right.
• Bordas relativas a um elemento (quando anchor.to === '#someId'): right-of, left-of, below, above, align-top, align-bottom, align-left, align-right.

Cada borda relativa a um elemento põe um canto do elemento sobre um canto do elemento em que ele se ancora, e offset o desloca a partir dali:

• right-of: o canto superior esquerdo sobre o canto superior direito do alvo (ao lado dele, topos alinhados); left-of: o canto superior direito sobre o canto superior esquerdo do alvo;
• below: o canto superior esquerdo sobre o canto inferior esquerdo do alvo (embaixo dele, bordas esquerdas alinhadas); above: o canto inferior esquerdo sobre o canto superior esquerdo do alvo;
• align-top e align-left: o canto superior esquerdo sobre o canto superior esquerdo do alvo. Os dois nomes dão o mesmo posicionamento: tanto a borda superior quanto a esquerda ficam alinhadas;
• align-bottom: o canto inferior esquerdo sobre o canto inferior esquerdo do alvo;
• align-right: o canto superior direito sobre o canto superior direito do alvo.

Uma borda relativa a um elemento usada com 'container', 'page' ou 'bleed', e uma borda de contêiner usada com '#id', são lidas como o canto superior esquerdo.

anchor.to: 'page' ancora o elemento na caixa de refile (a página física depois do corte) e 'bleed', na caixa de refile ampliada por cutLines.bleed em todos os lados (idêntica à caixa de refile enquanto as marcas de corte estão desativadas). Os dois quadros também passam a ser a referência para size: 'fill' e para a limitação automática de largura, de modo que uma faixa colorida pode ir de borda a borda, independentemente das margens da página:

{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }

Com as marcas de corte ativadas, tudo o que um elemento pinta além da caixa de sangria é cortado (veja Marcas de corte).

anchor.to: 'outer' (espaços de cabeçalho e de rodapé) ancora o elemento na margem externa da página: da borda da mancha até a borda de refile, no lado oposto à lombada, e do topo da mancha até o pé. Ela fica à direita de uma página ímpar e à esquerda de uma página par em um livro com encadernação à esquerda, e o contrário em um com encadernação à direita (page.binding), de modo que um único elemento serve às duas páginas de uma página dupla: um cabeço descendo pela margem externa (veja Elementos de texto verticais). Em qualquer outro espaço, é lida como 'container'. O offset de um elemento de texto pode ser escrito em em, ems do seu próprio fontSize: quatro caracteres abaixo do topo da mancha é { "y": { "value": 4, "unit": "em" } }.

Dentro do espaço de design avançado de um título, os elementos ancorados na página e na sangria não aumentam a altura reservada para o título, a menos que se estendam abaixo da borda superior do título (uma faixa no alto da página fica atrás da abertura; uma faixa que desce abaixo do título empurra o texto corrido para baixo). Use advancedDesign.minHeight para reservar uma altura fixa de abertura em qualquer caso, e reserve: false em um elemento que não deve empurrar o texto de jeito nenhum. As regras completas estão em Altura reservada.

Cada elemento tem um id estável (atribuído automaticamente pelo Sandbox; você também pode defini-lo à mão). Os elementos ancorados em outros elementos formam um pequeno grafo de dependências que o motor resolve antes de medir, então um elemento pode se encadear em outro sem coordenadas manuais.

O formato antigo align + marginFromBody + marginFromEdge é interpretado na entrada e reescrito como um posicionamento no momento em que a configuração é resolvida, então as configurações existentes continuam funcionando sem mudanças.

#Texto do corpo

A propriedade bodyText controla a tipografia de todo o texto dos parágrafos.

#Citações

Uma citação em bloco (linhas que começam com >) usa a família, o tamanho, a entrelinha, os pesos, o alinhamento e a hifenização do corpo. bodyText.blockquote define o resto; sem definição, uma citação fica como era até o postext 1.4: cinza, em itálico, com o recuo de primeira linha do corpo e sem recuo lateral.

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // Upright verse in the body colour, set in by 2 em, no first-line indent.
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

No Sandbox, estas opções formam o grupo Citações da seção Texto do corpo.

#Uma família por fontFamily

fontFamily (aqui e em todos os outros campos de família tipográfica: headings.fontFamily, tableStyle.bodyFontFamily, separatorFontFamily, o fontFamily de um estilo de chip ou de um elemento de design…) nomeia uma família. O canvas, a saída HTML e o PDF precisam compor com a mesma fonte, e o PDF incorpora uma fonte por família, sem cadeia de alternativas, então não há para onde uma pilha de fontes CSS recorrer. Uma pilha é composta na primeira família e reportada como aviso de configuração:

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // set in EB Garamond

Carregue essa família antes de diagramar (veja Fontes personalizadas e o provedor de fontes em Gerar PDFs); se ela estiver ausente, o navegador mede com a fonte padrão dele, diga o resto da pilha o que disser. Uma vírgula entre aspas faz parte de um nome ('"Foo, Bar"' é uma família).

#Hifenização

Quando o alinhamento do texto é 'justify', a hifenização evita o espaçamento excessivo entre palavras, dividindo as palavras longas nos limites de sílaba. O motor usa os padrões TeX/Liang para encontrar os pontos de quebra naturais entre sílabas. Veja Hifenização e justificação para uma explicação detalhada. O texto em bandeira só é hifenizado quando você pede: veja Texto em bandeira abaixo.

Idiomas suportados: 'en-us' (inglês), 'es' (espanhol), 'fr' (francês), 'de' (alemão), 'it' (italiano), 'pt' (português), 'ca' (catalão), 'nl' (holandês).

As subtags de região, escrita e variante são ignoradas na escolha dos padrões, assim como a caixa das letras e os separadores _: 'es-ES', 'es-MX' e 'es_419' hifenizam com 'es', 'pt-BR' com 'pt', e toda tag inglesa ('en', 'en-GB') com 'en-us', os únicos padrões ingleses incluídos, de modo que o texto britânico recebe quebras americanas. Um idioma sem padrões incluídos ('sv', 'pl', 'fi'…) é hifenizado com os padrões 'en-us', o que produz quebras erradas em vez de nenhuma; o motor o reporta uma vez por tag com um console.warn, e o Sandbox o lista no painel Verificações. Defina enabled: false para um documento assim; isso também silencia o aviso. Chinês, japonês e coreano (zh, ja, ko, qualquer que seja a região ou a escrita) não precisam de padrões nem geram aviso: um documento em um desses idiomas é composto sem hifenização. Para dividir as palavras latinas citadas nele, defina enabled: true e indique o idioma delas em locale ('en-us' para o inglês). enabled: true sem locale, ou com um idioma chinês, japonês ou coreano, deixa a hifenização desativada e avisa uma vez no console. matchHyphenationLocale(tag) devolve o idioma incluído que corresponde a uma tag (undefined quando não há nenhum), e HYPHENATION_LOCALES lista os incluídos. A configuração resolvida (doc.config.bodyText.hyphenation) indica em locale os padrões realmente usados e guarda em tag a tag que você informou, quando for diferente. O renderizador de PDF declara o idioma do documento a partir do locale do nível superior, e a partir desta tag só quando locale não está definido (veja Idioma do documento).

import { matchHyphenationLocale } from 'postext';
 
matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined: hifenizado com 'en-us', com um aviso no console

Palavras com menos de 5 caracteres nunca são hifenizadas. O motor exige pelo menos 2 caracteres antes e 3 caracteres depois de um ponto de quebra.

Texto em bandeira

Por padrão, só o texto justificado é hifenizado: com textAlign: 'left', e nos estilos de parágrafo alinhados à esquerda, ao centro ou à direita, toda palavra é mantida inteira, por mais irregular que a borda fique, exceto em um hífen condicional (U+00AD) digitado no texto. Defina hyphenation.ragged: true para hifenizar também o texto em bandeira.

Uma linha em bandeira nunca é esticada, então dividir toda palavra que não cabe encheria a borda de hífens. A zona de hifenização limita isso, como faz o compositor de linha única de um programa de editoração. Quando uma palavra não cabe no fim de uma linha, o motor olha o vazio que mandá-la inteira para a linha seguinte deixaria. Se esse vazio for maior que zone, a palavra é dividida na última sílaba que cabe; caso contrário, desce inteira. Uma zona em em é relativa ao tamanho da fonte do próprio texto. O padrão, 3em, só divide as palavras que deixariam uma linha visivelmente curta. Uma zona maior dá menos hífens e uma borda mais irregular; 0 divide toda palavra que não cabe. Na composição linha a linha, no máximo duas linhas seguidas terminam em sílaba. Hífens fixos (enseñanza-aprendizaje), junções de URL, hífens condicionais digitados no texto e palavras mais largas que a linha inteira quebram como sempre: a zona e o limite de duas linhas só regem as sílabas do dicionário.

A configuração vale para o documento inteiro. Aplica-se ao texto do corpo e às citações quando estão em bandeira, e a todo estilo de parágrafo e corpo de boxe em bandeira cuja hyphenation própria esteja ativada (por padrão, ela segue o hyphenation.enabled do corpo), de modo que hyphenation: false mantém inteiras as palavras de um estilo. Títulos, legendas, notas, células de tabela e o sumário não são hifenizados; ali, como em todo lugar, só uma palavra mais larga que a medida inteira é dividida. O texto de design (cabeços, aberturas, páginas de parte) segue a opção hyphenate de cada elemento de texto, que as aberturas de página inteira e as páginas de parte embutidas ativam, e usa também o dicionário do documento. O texto justificado ignora ragged e zone.

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // Um pouco mais de hifenização que o padrão de 3 em.
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};

Com optimalRagged (o padrão), o texto corrido em bandeira é quebrado com Knuth-Plass, e a zona mantém o seu sentido ali: uma palavra só é dividida quando não cabe no restante da linha e mandá-la inteira para baixo deixaria vazio mais que a zona. Duas sílabas seguidas não são recusadas, mas custam o que custam dois hífens seguidos no texto justificado, então uma terceira é rara. Com optimalRagged: false, ou optimalLineBreaking: false, cada linha é preenchida antes da seguinte, como até o postext 1.4.

A hifenização do texto em bandeira diagrama os parágrafos com o algoritmo de quebra que os parágrafos com formatação inline (negrito, itálico, links, fórmulas) sempre usam, então ativá-la pode mudar algumas quebras além dos hífens. Em uma linha em bandeira, além dos espaços e das sílabas do dicionário, esse algoritmo quebra depois de um hífen fixo ou de um travessão entre duas palavras (largas—separadas; com breakAfterDashes, qualquer travessão colado entre palavras, também riddles.—I e riddles—*and*), nas junções de URL e entre ideogramas, e mantém junta uma palavra composta em vários trechos (**Nota**:, (*véase*). Sem a hifenização do texto em bandeira, um parágrafo em bandeira sem formatação é quebrado com Knuth-Plass quando optimalRagged está ativado (o padrão): nos espaços entre palavras, depois de um hífen fixo entre duas letras (meta- · analyses), como faz o outro algoritmo, e, com breakAfterDashes, depois de travessões colados. Na composição linha a linha, ele passa pelo algoritmo de quebra do pretext, que difere em três pontos: também pode quebrar antes de um travessão que fecha um aparte ou depois de um que o abre (él · — y), depois de uma barra ao hifenizar (km/ · h), e corta uma palavra mais larga que a linha em qualquer caractere, sem hífen, onde o outro algoritmo a divide primeiro em uma sílaba.

No Sandbox, a opção é Hifenizar texto em bandeira, abaixo do alinhamento de parágrafo da seção Texto do corpo, com a zona logo abaixo. Com o corpo justificado, a mesma opção fica junto das configurações de justificação, para os estilos de parágrafo e os boxes em bandeira.

#Idioma do documento

O locale de nível superior é o idioma do documento como um todo. Aceita os mesmos valores que hyphenation.locale e é o valor que esse campo usa quando não está definido, de modo que basta locale: 'es' para um livro em espanhol ser hifenizado em espanhol. Ele também escolhe o idioma das strings integradas de continuação de tabelas e de boxes divididos ((cont.) / Continued em vez de Continúa, veja Tabelas mais altas que a página e Marcas de um boxe dividido) e dos números de título escritos por extenso (Chapter One em vez de Capítulo uno, veja Números por extenso), e é o idioma marcado num PDF acessível. Sem definição, o motor assume 'en-us'; o Sandbox usa o idioma da interface e mostra o campo em Design › Sistema de escrita.

Ele escolhe também os tipos de recurso integrados. Quando resourceTypes não está definido, buildDocument numera e legenda com defaultResourceTypes(locale), então só locale: 'de' já dá Abbildung 1.1 e Tabelle 1.1. Quando locale não está definido, o idioma da hifenização ocupa o lugar dele, tanto para os tipos de recurso quanto para as strings das tabelas. Uma lista resourceTypes explícita sempre prevalece. As versões anteriores usavam os tipos em inglês qualquer que fosse o locale, a menos que você mesmo passasse defaultResourceTypes(locale); um documento que define locale e quer manter os rótulos em inglês passa resourceTypes: defaultResourceTypes('en'). Os livros do Sandbox e os pacotes levam a própria lista, então não são afetados.

Qualquer tag BCP 47 funciona aqui, como em hyphenation.locale: 'de-AT' recebe as strings em alemão. As strings integradas existem nos oito idiomas que a hifenização suporta, em chinês (em caracteres simplificados e tradicionais), em japonês e em árabe; qualquer outro idioma recebe as inglesas.

O chinês aceita zh, zh-Hans, zh-Hant, zh-CN, zh-SG, zh-TW, zh-HK, zh-MO e as formas longas (zh-Hant-TW), em maiúsculas ou minúsculas e com - ou _. As strings seguem a escrita, lida com Intl.Locale(tag).maximize(): zh, zh-CN e zh-SG são simplificado; zh-TW, zh-HK e zh-MO, tradicional. Já os padrões tipográficos que dependem do idioma seguem a região, como recomenda a clreq §1.2: CN, SG e MY contam como China continental, TW como Taiwan, HK e MO como Hong Kong, e uma tag sem região vale pela escrita (zh-Hant é Taiwan; zh e zh-Hans, a China continental). O japonês aceita ja, ja-JP, ja-Jpan e qualquer outra tag ja (isJapaneseLanguage(tag)); desde o postext 1.16 ele tem strings próprias e uma região própria, japan, cujos padrões tipográficos seguem a JLReq (veja Composição japonesa). Uma tabela de strings sem entrada em japonês dá inglês, nunca chinês. localeScript(tag), cjkRegionOf(tag), stringsKeyOf(tag) e sameContentLocale(a, b) dão essas leituras, e DOCUMENT_LANGUAGES lista os idiomas com strings integradas, cada um com o nome no próprio idioma (日本語 entre as entradas chinesas e العربية), como o seletor Idioma do documento do Sandbox os mostra.

O prefixo da legenda é o nome do tipo (Figura 1.1.). Os tipos chineses numeram dentro do capítulo com hífen, {h1}-{n} (图 1-1); com os ajustes de legenda labelNumberGap: '' e labelSeparator: '　' a legenda fica 图1-1　标题 (veja Estilo de legendas). O índice remissivo também segue o idioma: 见 e 另见 antes de uma referência cruzada, 符号 e 数字 sobre os símbolos e os números em chinês simplificado; 見, 另見, 符號 e 數字 em tradicional. O japonês numera seus tipos da mesma forma e compõe as legendas como 図1-1　題 sem os dois ajustes, escreve as referências cruzadas como 第3章, 2.3節 e 12ページ, dá à bibliografia o título 参考文献, e seu índice imprime 記号 e 数字 sobre os símbolos e os números e escreve as remissões com uma seta, →夏目漱石 para ver e →夏目漱石、森鷗外も見よ depois das páginas para ver também, com os rótulos em pé. O árabe numera seus tipos da mesma forma, {h1}-{n} (شكل 2-3), escreve as referências cruzadas como الفصل 3, القسم 2-1 e ص 12, dá à bibliografia o título المراجع, e seu índice imprime انظر / انظر أيضًا, رموز e أرقام, com a vírgula e o ponto e vírgula árabes (، ؛).

Um documento em chinês, japonês ou coreano declara o idioma na saída HTML (lang na raiz .pt-doc, com zh-Hant-TW inteiro) e no canvas que ele pinta (ctx.lang, no Chrome 136 e posteriores), para que o navegador desenhe as formas de glifo da região: o Unicode unifica os caracteres han, e um mesmo ponto de código tem aspecto diferente numa fonte taiwanesa e numa japonesa. Os demais documentos não levam lang, como antes. O PDF declara /Lang a partir de locale em todo documento, marcado ou não, com a escrita e a região. Um documento num idioma escrito da direita para a esquerda (árabe, persa, urdu, hebraico…) também declara o idioma: as formas linguísticas da fonte (locl) e a fonte substituta o seguem.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // hifeniza em espanhol
};

Algarismos do documento

O numerals de nível superior define os algarismos de todo número que o motor escreve: números de página e os rótulos de página do sumário, do índice e das referências a páginas; números de listas numeradas e de notas de rodapé; contadores de títulos e capítulos, {chapterNumber}; o {h1} e o {n} do número de uma figura e de uma referência a ela; {totalPages}, {bookTotalPages} e {numberDecimal}. 'latn' escreve 0–9, 'arab' os algarismos arábico-índicos ٠–٩ e 'arabext' os algarismos persas ۰–۹. Só o formato decimal muda (decimal, o arabic das listas ou um ajuste deixado no padrão), então um formato que o autor nomeia sai como foi nomeado: lower-roman continua i, ii, iii, e arabic-indic num documento latino ainda escreve ١, ٢, ٣. O texto do documento nunca é reescrito.

O padrão, 'auto', usa os algarismos de locale (defaultNumeralsFor(tag)): 'arab' para o árabe sem região ou com qualquer região fora do Magrebe (ar, ar-EG, ar-SA, ar-AE…), 'latn' para ar-MA, ar-DZ, ar-TN, ar-LY, ar-MR e ar-EH, 'arabext' para o persa (fa), o pashto (ps) e o urdu da Índia (ur-IN), e 'latn' para todo o resto, inclusive o urdu do Paquistão. O CLDR dá latn para um ar sem região e para ar-AE; os livros árabes do Machrek e do Golfo imprimem ٠–٩, e é isso que o Postext segue. Uma tag que nomeia seus algarismos os mantém: ar-MA-u-nu-arab. Uma página numerada com os algarismos do documento registra arabic-indic ou persian como pageNumberFormat, para que os rótulos de página do PDF mostrem os mesmos algarismos. Um valor desconhecido segue o idioma e é avisado como unknownNumerals.

Os números que o autor digita são lidos em qualquer um dos três sistemas: um item de lista ٣. começa em 3, e {startAt=٥}, :::numbering{startAt=٥}, :::space{lines=٢} e :::part{number="٣"} (para {numberDecimal}) leem o valor.

const config: PostextConfig = { locale: 'ar' };                     // ١، ٢، ٣
const maghreb: PostextConfig = { locale: 'ar-MA' };                 // 1, 2, 3
const forced: PostextConfig = { locale: 'ar', numerals: 'latn' };   // 1, 2, 3

Direção do texto

O direction de nível superior define a direção base do documento: 'ltr', 'rtl' ou 'auto' (o padrão), que é 'rtl' quando a escrita de locale vai da direita para a esquerda (árabe, persa, urdu, hebraico, siríaco, thaana, n'ko, adlam…, lida por directionOf(tag)) e 'ltr' nos demais casos. Um documento da direita para a esquerda é diagramado num quadro espelhado: as linhas começam à direita, a primeira coluna é a da direita, recuos, marcadores de lista, flutuantes, notas de rodapé e boxes ficam à direita, e page.binding: 'auto' o encaderna pela direita. A configuração resolvida só leva direction: 'rtl' num documento assim, de modo que um documento da esquerda para a direita se resolve como antes. Um valor desconhecido é lido como 'auto' e avisado como unknownConfigValue. O algoritmo bidirecional do Unicode (UAX #9) ordena os trechos de cada linha em qualquer direção: uma citação em árabe num livro em inglês se lê da direita para a esquerda no próprio lugar.

Dentro do documento, um título ou um contêiner ::: aceita {dir=ltr} ou {dir=rtl}, e os inline :ltr[…] e :rtl[…] isolam um trecho de texto (veja Direção do texto na marcação); um recurso de tabela aceita table.direction. Um bloco composto contra a direção do documento mantém o 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 dele começa.

Um ajuste que nomeia um lado se refere a um lado do texto ou do fluxo do corpo, nunca da folha, então um design feito para um livro em inglês continua funcionando quando o livro passa para o árabe. 'start' e 'end' são aceitos como nomes explícitos:

placement.rotate mantém o sentido físico numa página espelhada: uma figura girada no sentido horário fica girada no sentido horário na folha. Um host que lê o layout encontra o quadro espelhado em cada página (VDTPage.flow com direction: 'rtl', pageIsMirrored(page)) e a ordem visual dos segmentos de cada linha em VDTLine.order; flowToPage e pageToFlow convertem entre o fluxo e a folha. Veja Composição árabe.

const arabic: PostextConfig = { locale: 'ar' };                        // da direita para a esquerda, encadernado pela direita
const english: PostextConfig = { locale: 'en', direction: 'rtl' };     // forçado; raramente é o que você quer

#Idiomas e escritas

O Postext compõe escritas alfabéticas da esquerda para a direita, e o chinês e o japonês na horizontal e na vertical. Composição chinesa e Composição japonesa explicam como são compostos e quais ajustes os controlam; as chaves estão em Tipografia do Leste Asiático, Escrita vertical e Encadernação. O que cada escrita recebe:

• O chinês é composto pelo compositor CJK quando um parágrafo tem mais caracteres CJK do que espaços entre palavras: as linhas quebram entre caracteres segundo as regras de início e fim de linha de cjk.lineBreak (nenhuma linha começa com 。、」 ou ー, nenhuma termina com 「 ou （), mantêm inteiros —— e ……, um número com seus sinais e uma palavra latina, e uma linha justificada é espaçada entre os caracteres até a medida. A largura da pontuação, a pontuação pendente, o espaço entre han e latim, a grade de caracteres, os pontos de ênfase, as marcas de nome próprio e de título de obra, o rubi e as notas warichu seguem a região de locale, na linha horizontal ou na vertical (layout.writingMode: 'vertical-rl'). Um parágrafo latino que cita algumas palavras CJK mantém a quebra de linha ótima e pode quebrar ao lado delas; um colchete CJK, o ponto médio ou um sinal de largura total citado em texto latino (〈h〉, ％) não muda nada.
• O japonês passa pelo mesmo compositor com regras próprias desde o postext 1.16, as dos Requirements for Japanese Text Layout (JLReq) do W3C e da JIS X 4051: um locale ja dá a região japan, cujos valores automáticos definem os níveis de kinsoku da JLReq (kana pequenos e ー nunca abrem uma linha), pontuação de largura total com compressão de pares, um eme depois de ？！, o parêntese que abre um parágrafo na segunda metade do recuo, marcas de ênfase em forma de gergelim sobre o texto, títulos de obras entre 『』, furigana espaçados 1:2:1, contadores japoneses, notas e um índice ordenado pela leitura. As versões anteriores compunham o japonês com os padrões da China continental.
• O coreano passa pelo mesmo compositor e é composto sem hifenização, mas com os padrões da China continental: as regras próprias dele (KLREQ) não estão implementadas. O texto coreano quebra entre sílabas e também nos espaços.
• O árabe e as outras escritas da direita para a esquerda (persa, urdu, hebraico…) são compostos da direita para a esquerda: Composição árabe explica como. A direction do documento vem da escrita de locale, o algoritmo bidirecional do Unicode ordena as palavras latinas e os números dentro de cada linha, o livro é encadernado pela direita com a primeira coluna à direita, e todo número que o motor escreve usa os algarismos da região. Uma palavra que contém uma letra da escrita árabe nunca é hifenizada, espaçada nem cortada, e uma linha árabe justificada se estica nos espaços e com kashidas. Sinais vocálicos, ênfase, notas de rodapé e as strings do árabe estão em Texto árabe. O persa, o urdu e o hebraico recebem a direção, os algarismos e as regras de palavra inteira, mas nenhuma string integrada própria.

Há padrões de hifenização para oito idiomas (en-us, es, fr, de, it, pt, ca, nl); os tipos de recurso integrados e as strings de continuação existem nesses oito, em chinês, em japonês e em árabe. Chinês, japonês, coreano e os idiomas escritos da direita para a esquerda são compostos sem hifenização. Qualquer outro idioma é hifenizado com os padrões do inglês dos EUA, com um aviso no console, e recebe as strings em inglês. Para um documento assim, defina hyphenation.enabled: false e passe resourceTypes e as strings de continuação de tableStyle no idioma dele.

#Texto árabe

Estes ajustes servem ao texto em escrita árabe; nenhum muda um documento escrito em outra escrita. Composição árabe os explica junto com o resto de um livro árabe: direção, encadernação, algarismos, verso, sumário e índice.

• Sinais vocálicos e entrelinha. Os sinais vocálicos de um texto vocalizado (fatḥa, kasra, shadda, tanwīn, o alef sobrescrito, os sinais corânicos) se empilham sobre e sob as letras, dentro da entrelinha, que nunca cresce por causa deles. Cada linha com sinais registra até onde vai a tinta deles (VDTLine.markInk), e o recorte de coluna dos renderizadores inclui os sinais da primeira e da última linha da coluna. Quando um sinal sobre uma palavra encosta nas letras ou nos sinais pendurados sob a palavra de cima, a composição avisa o parágrafo (arabicMarksExceedLeading, no painel Verificações do Sandbox). Só se comparam palavras que estão uma sobre a outra. Texto parcialmente vocalizado pede cerca de 1,7–1,85 em de lineHeight; verso totalmente vocalizado, 1,9–2,1 em.
• Ênfase. A tipografia árabe não tem itálico, então num documento cujo locale se escreve em escrita árabe *…* sai em negrito por padrão (bodyText.emphasis: 'auto'). 'color' o compõe em redondo com italicColor, e 'overline' traça um fio sobre as palavras, o khaṭṭ fawqī dos livros árabes. O ajuste vale para todo texto composto com as fontes do corpo: parágrafos, listas, citações em bloco, estilos de parágrafo, corpo dos boxes, notas e títulos. Legendas, células de tabela, o sumário e o índice mantêm os próprios ajustes de itálico. Seja qual for a escolha, o motor nunca inclina letras árabes: as palavras árabes de um trecho em itálico ficam em pé e as palavras latinas mantêm o itálico. Num documento assim, a citação em bloco é em redondo por padrão.
• Tashkīl. bodyText.tashkil: 'strip' tira os sinais vocálicos e corânicos do texto que o layout compõe, para uma edição sem vogais feita a partir de uma fonte vocalizada: fatḥa, ḍamma, kasra e seus tanwīn, sukūn, shadda, o alef sobrescrito (هٰذا vira هذا) e os sinais U+0656–U+065F e U+06D6–U+06ED. 'strip-vowels' mantém a shadda, como a maioria dos livros modernos a imprime. Hamza e madda ficam (أ إ آ são letras, também quando digitadas com sinais combinantes). O original mantém os sinais; as linhas, os títulos e o sumário são compostos sem eles, e cada caractere composto continua apontando para o seu lugar no original.
• Notas de rodapé. footnotes.markerTemplate: '({n})' escreve as chamadas «(١)» nos algarismos do documento, numbering: 'page' recomeça a numeração em cada página e noteNumberPosition: 'inline' põe o número da própria nota na linha. O fio separador e os números das notas ficam no início da coluna, à direita num livro da direita para a esquerda.
• Palavras inteiras. Uma palavra que contém uma letra da escrita árabe nunca é hifenizada, cortada ou espaçada, num livro árabe ou citada em outro. Um estilo que aplica letterSpacing a texto árabe é avisado (joiningScriptLetterSpacing), e uma palavra mais larga que a linha transborda dela e é avisada (unbreakableWordOverflow). Veja Composição árabe.
• Kashida e verso. Uma linha árabe justificada se estica com kashidas além dos espaços (bodyText.kashida, veja Kashida no texto árabe), e um poema clássico é composto um bayt por linha, em dois hemistíquios de mesma largura, com :::verse (veja :::verse).
• Índice. Um índice em árabe ordena alfabeticamente e ignora o artigo ال (index.ignoreArticle), os sinais vocálicos e os suportes da hamza; veja Índice remissivo.

#Órfãs, viúvas, linhas curtas e regras de manter junto

Veja Hifenização e justificação para a mecânica por trás destes deméritos. Esta seção é a referência das chaves de bodyText que os controlam.

Além da hifenização e dos limites de espaçamento, a configuração do texto do corpo expõe as regras flexíveis que evitam quebras de parágrafo estruturalmente desajeitadas. Todas entram no algoritmo de quebra de linhas de Knuth-Plass como deméritos: elas puxam o layout para quebras limpas sem nunca impor uma regra rígida. Defina os valores *Penalty como 0 para desativar, na prática, qualquer uma delas.

Sobre linhas curtas. Uma linha curta é a última linha de um parágrafo curta demais para parecer uma linha de texto de verdade, em geral uma ou duas palavras curtas isoladas no fim do parágrafo. Como a verificação se baseia no comprimento da linha em pixels em relação à largura do espaço normal, runtMinCharacters se adapta sozinho ao corpo da fonte atual. Uma palavra curta que, visualmente, é mais larga que runtMinCharacters × spaceWidth não tem problema; uma palavra mais estreita que isso (ou realmente sozinha) recebe a penalidade de linha curta. O limite conta espaços entre palavras, que têm cerca de metade da largura das letras: o padrão 20 corresponde a uma última linha de mais ou menos 8 a 12 letras. Toda linha curta custa a penalidade inteira, então entre dois finais abaixo do limite o algoritmo de quebra mantém as linhas mais apertadas acima; gradedRuntPenalty cobra cada um pelo que lhe falta, e o final mais longo vence. Para os curiosos de matemática: com o runtPenalty padrão de 1000, evitar uma linha curta supera qualquer conjunto de quebras alternativo que exija um esticamento do espaçamento entre palavras de até cerca de r≈2,15.

Flexíveis, não rígidas. Nenhuma destas regras pode impedir uma quebra: o motor sempre produz um layout. São deméritos: o algoritmo pondera badness, custo de hifenização, suavidade das classes de aptidão e estas penalidades estruturais numa única otimização global e escolhe o conjunto de quebras com o menor custo total. Se você precisa de uma garantia mais firme, aumente a penalidade; se um documento fica melhor com a penalidade mais branda, diminua-a.

#Títulos

A propriedade headings controla a tipografia de todos os níveis de título (H1–H6). Você pode definir padrões gerais que valem para todos os níveis e depois sobrescrever propriedades específicas por nível.

#Padrões gerais

Títulos centralizados para poemas ou os atos de uma peça, sem posição de design:

headings: {
  textAlign: 'center',
  levels: [{ level: 2, textTransform: 'uppercase' }],
}

Passar um objeto headings mantém todo padrão de nível que você não repetir, inclusive a quebra de página do H1 (veja Sobrescritas por nível).

#Equilíbrio de colunas

As editoras esperam que toda coluna comece no alto da página e termine alinhada com o pé. As regras de quebra (proteção contra órfãs e viúvas, títulos mantidos com o seu texto, figuras indivisíveis) deixam naturalmente colunas curtas, com uma ou mais linhas vazias da grade de linhas de base no pé. Com o equilíbrio ativado, o motor faz o que um compositor faria e aplica seus recursos na ordem de prioridade editorial:

1. Um boxe que fecha a coluna: um boxe que termina uma coluna curta é empurrado para baixo exatamente pelo espaço que sobra sob o seu pé, de modo que a borda inferior cai na última posição da grade da página, alinhada com a última linha da coluna ao lado. Ele ocupa esse espaço mesmo quando é menor que uma linha, desde que nada passe para outra coluna. Por padrão, roda antes de qualquer outro recurso e ocupa a lacuna inteira, então um boxe que comenta o parágrafo acima dele pode acabar várias linhas abaixo; closingBox: 'last' deixa os títulos, os finais de lista e os outros recursos de espaçamento ficarem primeiro com as linhas inteiras, e o boxe só com o que sobrar, e closingBox: 'off' nunca o move.
2. Imagens com área segura: uma imagem com área segura (Resource.safeArea, veja Formato do documento › Área segura) inserida na linha da coluna curta, ou flutuando no alto ou no pé dela só sobre essa coluna, cresce em linhas inteiras da grade, recortada dentro da área segura, até a coluna ficar cheia ou o recorte chegar à área segura. Uma imagem mais alta não deixa buraco na página, por isso roda antes de qualquer espaço ser somado; um flutuante no alto de uma coluna numa página ou faixa cujas cabeças de coluna ficam niveladas (veja abaixo) não cresce. Registrado como flexFigure. Não tem ajuste próprio: só cresce uma imagem cujo recurso marca uma área segura.
3. Títulos: linhas inteiras da grade são somadas à margem superior dos títulos dentro da coluna curta. Quando são necessárias várias linhas e a coluna tem vários títulos, as linhas se distribuem entre eles, sempre com a maior parte para o título mais importante (um h2 recebe mais que um h3). Títulos no alto de uma coluna nunca recebem espaço extra, para que as colunas continuem começando no alto da página, exceto um título logo abaixo de uma figura ou tabela que encabeça a coluna numa página que continua: o espaço vai acima desse título, sob a figura.
4. Finais de lista: quando os títulos não conseguem absorver a lacuna inteira, uma linha da grade é somada onde uma lista ou enumeração termina (espaço depois de uma lista soa natural), com um limite por final de lista.
5. Parágrafos frouxos: como último recurso, um parágrafo da coluna é quebrado de novo com uma linha a mais (o \looseness=+1 do TeX), escolhendo o parágrafo mais longo para que o espaçamento extra entre palavras se dilua sem ser notado. A solução frouxa só é aceita quando toda linha fica abaixo de bodyText.maxWordSpacing: a cor tipográfica nunca passa do limite que você já configurou. Requer bodyText.optimalLineBreaking.

A última coluna de uma página só é equilibrada quando a página continua naturalmente na seguinte: a página de fechamento de um capítulo pode, legitimamente, terminar curta. Uma página assim, e uma faixa de fechamento cortada por igual por trailing, também mantém niveladas as cabeças de coluna: nenhuma linha é somada sob uma figura ou tabela que encabeça uma das colunas (o recurso de depois do flutuante), e um título ou um boxe que abre uma coluna sob essa figura fica no alto dela, diga o que disser stretchAfterFloats, de modo que uma coluna nunca começa mais abaixo que a vizinha só para alinhar os pés.

Qual recurso atuou

O layout registra cada recurso aplicado no bloco em que o aplicou: block.balancing no VDT que buildDocument devolve. Uma prova, um teste ou um relatório pode dizer por que uma coluna termina alinhada, e quais colunas nenhum recurso conseguiu fechar. Os blocos que o equilíbrio não tocou não levam balancing, e um documento construído com enabled: false não tem nenhum.

interface VDTBalancing {
  levers: BalanceLever[]; // em geral um: um parágrafo depois de uma lista pode ficar com a linha do final de lista e também ganhar uma linha
  spaceAbove: number;     // px que os recursos de espaçamento somaram acima do bloco (0 quando só atuou looseParagraph ou flexFigure)
  bodyGrowth?: number;    // flexFigure: px que a imagem cresceu, recortada dentro da área segura
  extraLines?: number;    // looseParagraph: linhas que o parágrafo ganhou
  tracking?: number;      // looseParagraph: o tracking que as ganhou, em milésimos de eme (0 = só espaçamento entre palavras)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

Os cortes por igual ficam registrados nas colunas que cortam: column.bandCapped é true em toda coluna cortada por igual (a faixa que um boxe de página inteira deixa, uma faixa de fechamento), e column.trailingCap marca também a faixa de fechamento de um capítulo ou do documento (trailing).

import { buildDocument } from 'postext';
 
const doc = buildDocument(content, config);
for (const page of doc.pages) {
  page.columns.forEach((column, i) => {
    const levers: string[] = column.blocks.flatMap((block) => block.balancing?.levers ?? []);
    if (column.trailingCap) levers.push('closing band cut level');
    else if (column.bandCapped) levers.push('band cut level');
    if (levers.length > 0) console.log(`page ${page.index + 1}, column ${i + 1}: ${levers.join(', ')}`);
  });
}
// page 3, column 1: heading, heading
// page 3, column 2: listEnd, looseParagraph

#Sobrescritas por nível

Cada nível de título pode sobrescrever os padrões gerais pelo array levels. Só fontSize (além do breakBefore do H1, comentado abaixo) muda por padrão; todas as outras propriedades herdam dos ajustes gerais de título.

O padrão do H1 reproduz a diagramação de capítulos de um livro: todo título de nível superior abre numa página nova à direita (ímpar), com uma página em branco separadora obrigatória depois do capítulo anterior. Sobrescreva-o em levels[0].breakBefore se o seu documento for mais simples que um livro.

O breakBefore de um nível é mesclado campo a campo sobre esse padrão, e um objeto headings que não o menciona o mantém. { parity: 'odd' } no H1 mantém a quebra e muda só a paridade; { enabled: false } deixa os capítulos seguirem em sequência:

headings: {
  fontFamily: 'Merriweather',                               // o H1 continua quebrando para um recto novo (always-odd)
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // …ou: um recto, sem página em branco obrigatória
}
 
headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // capítulos em sequência

Mudou no postext 1.5. Até o postext 1.4, qualquer objeto headings desligava a quebra do H1 a menos que levels[0].breakBefore fosse repetido, e um breakBefore parcial completava o campo que faltava com o padrão sem quebra. Por isso, uma configuração escrita em código para a 1.4 com um objeto headings e sem quebra no H1 agora abre todo capítulo num recto novo, com versos em branco onde for preciso. Para manter os capítulos em sequência, dê um campo à entrada H1 de levels:

headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // como a 1.4 diagramava

Onde a configuração ficou salva, o motor consegue perceber e faz isso por você: o Sandbox, nos livros e configurações que salvou na época (veja Sandbox → Persistência), e openBundle / readBundle, num pacote .postext gravado pelo postext 1.4 ou anterior (veja Pacotes gravados pelo postext 1.4 ou anterior). Uma configuração que você mesmo salvou pode passar por migrateConfig(config) de postext/bundle, que grava as quebras como a 1.4 as diagramava (pinLegacyHeadingBreaks): enabled: false num H1 que não tinha quebra, e parity: 'any' ao lado de um enabled: true que não indicava paridade, no H1 e nos estilos de título. Ele também fixa o tamanho das fórmulas, o espaço em volta das figuras na linha (também nos boxes), as marcas na linha dos títulos, o tamanho das capitulares, o espaço sob uma linha com dois-pontos que introduz uma lista, as linhas que o corte de um boxe deixa de um parágrafo ou de um item de lista, as quebras de linha em travessões, a quebra linha a linha do texto alinhado à esquerda, a divisão de um parágrafo sob um título, as quebras de linha no hífen de uma palavra composta e o espaço sob os contêineres :::paragraphs, como a 1.4 os compunha. Passe o markdown do livro como terceiro argumento, { content }, e ele deixa de fora a fixação das fórmulas quando o texto não tem nenhum $, as das lacunas quando nenhuma linha insere um recurso (a da lacuna nos boxes quando nenhuma o faz dentro de um boxe), a das marcas quando nenhum título tem marcas, a dos dois-pontos quando nenhuma lista vem depois de uma linha terminada em dois-pontos, a do corte de boxes quando o texto não abre nenhum :::callout, a dos travessões quando nenhum travessão está colado entre palavras, a da divisão sob título quando o texto não tem títulos, a dos contêineres quando o texto não abre nenhum contêiner :::paragraphs, e a das palavras compostas quando nenhum hífen está entre duas letras; a da quebra do texto alinhado à esquerda só vai para uma configuração que deixa algum texto corrido alinhado à esquerda, e a dos contêineres só para uma que declara um estilo de parágrafo (veja Pacotes gravados pelo postext 1.4 ou anterior). Para fixar só as quebras, chame pinLegacyHeadingBreaks(config).

As sobrescritas por nível aceitam as mesmas propriedades que os padrões gerais (fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom, snapToGrid) e mais estes campos exclusivos de nível (um estilo de título também os aceita):

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Predefinição canônica de livro: capítulos numa página à direita (ímpar).
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

snapToGrid também funciona por nível. Sem definição, um nível segue headings.snapToGrid; definido, o sobrescreve. Assim, um documento pode pôr os H2 a uma linha e meia do texto, fora da grade até o próximo ponto de ajuste, enquanto os H3 arredondam o espaço sob eles para linhas inteiras da grade. Um estilo de título também pode defini-lo, para os títulos que o usam.

headings: {
  marginBottom: { value: 1.5, unit: 'em' },
  levels: [
    { level: 2, snapToGrid: false }, // exatamente 1,5 em sob cada H2
    { level: 3 },                    // herda headings.snapToGrid: true
  ],
}

#Quebra antes

breakBefore é independente dos controles de numeração: ativá-lo força uma quebra de página, mas o contador numérico só recomeça quando você insere explicitamente uma diretiva :::numbering. As páginas em branco de paridade contam como páginas reais na sequência e recebem cabeçalhos e rodapés segundo as regras normais de par e ímpar.

Um :::pagebreak logo antes de um título assim não substitui a quebra dele: o título continua aplicando a paridade depois da página que a diretiva abriu, o que pode somar uma página em branco. Veja Estilos de título para um título que deve começar logo depois de uma quebra manual.

Valores de paridade

A quem pertencem as páginas em branco

As páginas em branco inseridas por breakBefore levam cabeçalhos com o título do capítulo conforme o motivo pelo qual foram inseridas:

• As páginas inseridas para cumprir uma restrição de paridade ('odd', 'even' ou a parte de paridade de 'always-*') pertencem ao capítulo seguinte. O marcador {chapterTitle} do cabeçalho delas resolve para o título do novo capítulo, porque a página em branco só existe para levar o novo capítulo à paridade certa.
• A separadora obrigatória inicial inserida por 'always-odd' / 'always-even' pertence ao capítulo anterior. É uma pausa deliberada de fim de capítulo, então o cabeçalho {chapterTitle} ainda mostra o título do capítulo antigo.

Os cabeços e a paleta de uma seção com estilo (veja Estilos de título) seguem as mesmas duas regras nas páginas em branco.

Exceção do início do documento

Quando o primeiríssimo bloco do documento é um título com breakBefore ativado (ou a fonte abre com :::pagebreak), a paridade não é aplicada enquanto a primeira página ainda está vazia. O título cai na página 1, como escrito, qualquer que seja a paridade configurada, de modo que um documento que começa com um # Chapter 1 configurado com parity: 'odd' não herda uma página em branco inicial espúria. Depois que algum conteúdo foi colocado, a paridade é aplicada normalmente.

#Largura e design avançado

Cada nível de título aceita dois campos adicionais que controlam como o título é renderizado como abertura de capítulo na largura da página inteira.

Uma abertura tão alta quanto a página. Quando a altura reservada passa do pé da coluna (uma capa cuja minHeight é a altura da página, uma imagem ou um boxe ancorado na página ou na sangria que desce até o refile), a abertura toma o resto da página: o texto que vem depois dela começa na página seguinte, em todas as colunas, tanto num layout de duas colunas quanto num de coluna e meia. Por isso uma capa não precisa de um :::pagebreak depois dela (um não faz mal: não acrescenta página em branco). Um título de coluna (span: 'column') cujo design é mais alto que sua coluna toma essa coluna, e o texto começa no topo da seguinte. O bloco do título desce então até o pé da coluna que ele toma, e seu design é composto contra essa faixa: os elementos ancorados no topo ficam onde estão ancorados, e os que acompanham a faixa (ancorados no meio ou no pé dela, ou com altura 'fill') se limitam ao espaço que o título toma, como se limitam à altura reservada quando ela cabe (até o postext 1.4 o bloco mantinha a altura do seu texto, de modo que esses elementos eram compostos contra uma faixa da altura de um título, e o texto seguinte continuava por baixo do design). Elementos fixos da página que não devem tomar a página (uma tarja na margem externa ao longo de toda a página, um ornamento no pé da página) ficam melhor no design do cabeço ou do rodapé: ancorados em 'page' ou 'bleed' e exibidos com pages: 'opener', são pintados na página de abertura e não reservam espaço no corpo.

Exemplo: uma abertura de capítulo minimalista que mostra “Chapter N” acima do título:

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Chapter {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

Marcadores de título disponíveis dentro do espaço de design de um nível:

• {titleText}: o texto simples do título (sem o prefixo de numeração). Uma quebra forçada no título (\\) é aqui uma quebra de linha, tanto numa faixa de abertura quanto num design de coluna (até o postext 1.4 um design de coluna imprimia um espaço ali, embora sua altura fosse medida com a quebra). As linhas em que o título oculto se quebra na sua coluna são reunidas de novo no título tal como foi escrito: uma palavra quebrada depois do seu próprio hífen mantém o hífen, sem espaço depois dele; uma palavra que a coluna dividiu volta a ficar inteira, sem o hífen que a quebra acrescentou; um grupo unido por um espaço inseparável que era mais largo que a coluna e foi separado nesse espaço recupera o espaço inseparável (Capítulo XVIII, não CapítuloXVIII); e cada uma das outras quebras devolve o seu espaço. Até o postext 1.4 toda quebra de linha virava um espaço, de modo que um título quebrado num hífen imprimia Word- Book, e uma quebra forçada num título assim se perdia.
• {number}: o número formatado segundo o numberingTemplate do nível.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower}: o contador do título (a contagem corrente do seu nível, seja o que for que o modelo imprima) em outros formatos de numeral: o terceiro capítulo dá 3, III, iii, C, c, com ou sem numberingTemplate. Um título não numerado (um estilo com numbered: false) os deixa vazios.
• {numberWords}, {numberWordsLower}, {numberOrdinalWords}, {numberOrdinalWordsLower}: o mesmo contador por extenso, com maiúscula inicial ou em minúsculas: Three / three, Third / third (veja Números por extenso).
• {numberHan}: o mesmo contador em numerais chineses, na escrita do locale do documento: uma abertura composta com 第{numberHan}回 imprime 第十二回 no décimo segundo capítulo, enquanto o sumário mostra 12.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {bookTotalPages}, {title}, {subtitle}, {author}, {publishDate}: marcadores de metadados compartilhados.
• {attr.<key>}: um atributo escrito na própria linha do título (# Title {author="I. Zango Martín"}), que recorre ao atributo do H1 do capítulo atual. Atributos ausentes resultam numa string vazia, sem aviso.

{chapterNumber} imprime o que os cabeços imprimem para o capítulo: o número do H1 quando o seu nível (ou estilo) tem um numberingTemplate; caso contrário, o ordinal do capítulo (1, 2…, continuando depois dos capítulos diagramados antes deste); e nada num capítulo não numerado ou num estilo cujo modelo é ''. O design de um título lê o capítulo ao qual o título pertence: um título de nível 1, o seu próprio; um título inferior, o último título de nível 1 antes dele. Isso vale também quando dois capítulos se encontram numa mesma página, embora os cabeços dessa página imprimam o capítulo posterior. A altura que uma abertura reserva é medida com esse mesmo valor. Até o postext 1.4 ela era medida com o prefixo de número do título (vazio sem modelo), de modo que um design cuja altura dependesse de {chapterNumber} podia ser pintado mais alto que o espaço que ocupava; e o design imprimia o capítulo da página, de modo que o primeiro de dois capítulos que dividiam uma página mostrava o número do segundo.

Os marcadores de contador acompanham o livro através de capítulos diagramados um de cada vez (os contadores que continuationAfter() repassa), e o atributo startAt de um título os reinicia (veja Formato do documento → Atributos de título). Uma abertura que diz Chapter III acima de um título numerado 3. no fluxo e no sumário:

{
  level: 1,
  span: 'page',
  numberingTemplate: '{1}.',
  advancedDesign: {
    enabled: true,
    slot: { elements: [
      { kind: 'text', id: 'label', content: 'Chapter {numberRoman}', fontSize: { value: 10, unit: 'pt' }, overflow: 'ellipsis-end',
        placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill', height: 'auto' } } },
      { kind: 'text', id: 'title', content: '{titleText}', fontSize: { value: 24, unit: 'pt' }, overflow: 'wrap',
        placement: { anchor: { to: '#label', edge: 'below' }, size: { width: 'fill', height: 'auto' } } },
    ] },
  },
}

Altura reservada

Um título com design avançado ocupa espaço na coluna como qualquer bloco: o texto do corpo que vem depois dele começa abaixo desse espaço. O espaço é a maior de três alturas, todas medidas para baixo a partir do topo do título (o topo da área de conteúdo, numa abertura que começa a sua página):

1. o próprio texto do título, composto na tipografia do nível (fica oculto sob o design, mas mantém suas linhas);
2. a base do conteúdo do design: a borda inferior mais baixa entre os elementos que contam (veja abaixo);
3. advancedDesign.minHeight.

A marginBottom do título é somada depois (do seu estilo de título, do seu nível ou de headings.marginBottom; 0,5 em por padrão), e o resultado é arredondado para cima até a grade de linhas de base quando os títulos se ajustam a ela. Numa abertura (span: 'page'), a mesma faixa fica livre em todas as colunas da página. Num título de coluna que cabe na sua coluna, o design é composto na caixa do título, que tem exatamente essa altura.

Quais elementos contam. Todos os elementos do design contam (textos, fios, caixas e imagens; até o postext 1.4 um elemento image nunca contava, de modo que o texto podia começar por cima de uma imagem da faixa, a menos que minHeight o afastasse), exceto:

• os elementos com reserve: false: decoração que pode ficar sob o texto;
• os elementos que acompanham a própria faixa: ancorados na linha do meio do contêiner (left, center, right) ou na linha de baixo (bottom-left, bottom, bottom-right), com altura 'fill' em relação ao contêiner (uma caixa ou um fio vertical sem altura o preenche por padrão), e qualquer elemento ancorado num deles. O contêiner é a faixa reservada, então esses elementos ficam no pé dela ou a atravessam: um fio sob a faixa, um painel colorido atrás do título. Eles acompanham a altura; nunca a definem. Um texto entre eles que mantém sua própria altura ainda precisa de espaço: um título ancorado no pé da faixa deixa a faixa pelo menos tão alta quanto o título, de modo que o título nunca começa acima do topo do título oculto. Com minHeight: 36mm e o título ancorado em bottom-left, a caixa do título tem 36 mm mais a sua marginBottom, arredondada para cima até a grade, e o título fica no pé dessa caixa, logo acima do texto que vem depois; sem minHeight, um título que ocupa mais linhas que o texto oculto deixa a faixa tão funda quanto o título. Até o postext 1.4 um título assim era pintado para cima, sobre o texto acima do título oculto. Caixas, fios e imagens que acompanham a faixa não impõem esse piso, então um painel ancorado no pé pode subir acima do título.

Os elementos ancorados na página e na sangria contam pelo quanto descem abaixo do topo do título. Uma faixa no alto da página que termina acima do título não conta nada; uma imagem sangrada que passa dele empurra o texto até a sua borda inferior. O mesmo acontece com tudo o que fica baixo na página: um selo a 25 mm do pé da página, uma faixa lateral de altura inteira ou uma moldura reservam a página até a sua borda inferior, e o texto em geral começa na página seguinte. Marque essa decoração com reserve: false (ela continua sendo pintada e outros elementos ainda podem se ancorar nela) e dê ao título o espaço de que ele precisa com os seus elementos de texto ou com minHeight:

{
  "kind": "image", "id": "seal", "resourceId": "seal", "reserve": false,
  "placement": {
    "anchor": { "to": "page", "edge": "bottom-right" },
    "offset": { "x": { "value": -25, "unit": "mm" }, "y": { "value": -25, "unit": "mm" } },
    "size": { "width": { "value": 30, "unit": "mm" } }
  }
}

Um elemento ancorado num elemento que não reserva espaço continua contando, a menos que também seja marcado (uma legenda posta no selo precisa do seu próprio reserve: false).

Onde é pintado. O design de uma abertura (span: 'page') é desenhado antes do corpo, então a decoração que não reserva nada fica sob o texto. O design de um título de coluna é desenhado junto com o bloco do título (por cima dos blocos acima dele na coluna, por baixo dos que vêm depois) onde quer que esteja posicionado acima do pé da sua coluna: também nas margens laterais, na margem superior, na sangria e nas colunas vizinhas. O pé da coluna o corta, no canvas e no PDF, porque o fluxo termina ali (veja Mais alto que a coluna, abaixo). Até o postext 1.4 o canvas e o PDF também o cortavam no topo da sua coluna, de modo que uma faixa ancorada no topo da página ou da sangria entrava nas margens laterais, mas parava na margem superior. Decoração ancorada no pé da página fica melhor numa abertura, ou no design do rodapé com pages: 'opener'.

Mais alto que a coluna. Quando o espaço passa do pé da coluna (uma minHeight tão alta quanto a página, uma imagem ou uma moldura que desce até o refile), o título toma o resto da sua página (uma abertura, em todas as colunas) ou da sua coluna (um título de coluna), e o texto que vem depois dele começa na página ou na coluna seguinte. Seu bloco vai então até o pé da coluna, nunca reduzido à altura do seu texto, de modo que a faixa contra a qual o design é composto é o espaço que ele toma (minHeight incluída, até o pé). Um design mais alto que a própria página (uma linha fina longa numa página de tela pequena) continua sendo cortado no pé da página (um design de coluna, no da sua coluna): o Sandbox o lista no painel Verificações como Design do título cortado. A diagramação não emite aviso por isso (uma capa que toma a sua página é o caso comum e não perde nada), mas qualquer aplicação pode fazer a mesma verificação no layout pronto: collectHeadingDesignCuts(doc) devolve um { kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd } para cada título cujo texto de design fica além do pé do refile da página (where: 'page', uma abertura) ou da sua coluna (where: 'column'), e formatWarning descreve cada um. Veja Uma abertura tão alta quanto a página em Largura e design avançado.

A coluna lateral. Num layout de coluna e meia cuja coluna lateral recebe flutuantes (sideColumnRole: 'floats'), um elemento do design de um título de coluna que fica na coluna lateral (um numeral de capítulo ancorado na página, na coluna da margem externa da abertura de um livro didático) mantém a pilha lateral longe dele. Cada figura, tabela ou boxe span: 'side' que a página compõe depois do título mantém um espaço entre flutuantes livre em relação a cada um desses elementos: fica onde a pilha o coloca quando cabe acima do elemento e, caso contrário, vai para baixo dele, ou espera a página seguinte quando o resto da coluna lateral não o comporta ali. Assim, um numeral no alto do canal mantém a pilha inteira abaixo dele, enquanto um número de seção pendurado na margem ao lado de um título mais abaixo na página deixa o alto do canal para as figuras que a página cita (a figura marginal continua no topo da sua página). O que a coluna lateral já contém quando o título é posicionado não se move: uma figura empilhada antes na página que desce até o elemento do título fica onde está, sob o elemento, então um design cujo elemento fica na coluna lateral no meio da página pede que as suas figuras sejam citadas depois do título. Os elementos com reserve: false deixam a coluna lateral livre, como deixam o texto. Uma abertura (span: 'page') não precisa de nada disso: a sua faixa é reservada em todas as colunas, inclusive na lateral. Até o postext 1.4 uma figura lateral citada numa abertura assim era composta no alto da coluna lateral, por cima do numeral.

Capas. Um título de capa que preenche a sua página (minHeight tão alta quanto a página, ou uma imagem de página inteira no seu design) manda, portanto, o texto que vem depois dele para a página seguinte por si só, em layouts de uma ou de várias colunas. Um :::pagebreak logo depois dele é opcional e não faz mal: uma quebra de página numa página ainda vazia não faz nada, então nunca acrescenta uma página em branco. Ele só é necessário quando o design da capa para antes do pé da página e o texto ainda assim deve começar numa página nova.

# Annual report 2026 {style="cover"}
 
:::pagebreak
 
# Letter from the chair

#Números por extenso

Dois sufixos de modelo de numeração escrevem um contador por extenso, no idioma do documento (o locale de nível superior ou, na falta dele, o idioma de hifenização; veja Idioma do documento): words para o cardinal e ordinal para o ordinal. A caixa do sufixo define a caixa das palavras, como A / a faz com as letras:

Inglês, espanhol, chinês e árabe são escritos por extenso; qualquer outro idioma usa as palavras em inglês, como fazem as strings de continuação de tabela embutidas. O chinês escreve os numerais informais de simp-chinese-informal ou trad-chinese-informal, conforme a escrita do locale (一万 / 一萬), com 第 antes de um ordinal; os caracteres Han não têm caixa, então as três grafias de um sufixo imprimem o mesmo. O inglês segue o uso americano (one hundred five, sem and). O espanhol usa formas masculinas, como se numera um capítulo ou um libro (capítulo primero, tercero, veintiuno), e escreve os ordinais de 13 a 29 numa só palavra, como prefere a RAE (decimotercero, vigesimoprimero). Os cardinais são escritos por extenso até 999 999, e os ordinais em espanhol até 999; números maiores saem em algarismos.

Os números em árabe concordam em gênero com o substantivo que contam, então o sufixo aceita um modificador: -feminine (ou -f) para um substantivo feminino, -masculine (-m, o padrão) para um masculino; -classical escreve as centenas مائة, como fazem Bulaq e a maioria das edições egípcias, em vez do moderno مئة. {1:ordinal} escreve o ordinal definido no nominativo que um título usa: الفصل {1:ordinal} dá الفصل الأول, الفصل الحادي عشر, الفصل الحادي والعشرون; الليلة {1:ordinal-feminine} dá الليلة الأولى, الليلة الحادية عشرة, الليلة الحادية والعشرون, الليلة المئتان, e acima de cem a fórmula clássica de “depois”: الليلة الخامسة والأربعون بعد الثلاثمئة, الليلة الحادية بعد الألف. {1:words} escreve o cardinal (واحد وعشرون; feminino إحدى عشرة, واحدة وعشرون). Os ordinais são escritos por extenso até 9 999 e os cardinais até 99 999; os modificadores se combinam ({1:ordinal-f-classical}), e os outros idiomas os ignoram. O árabe não tem maiúsculas, então a caixa do sufixo não muda nada. Os marcadores de design {numberWords} e {numberOrdinalWords} escrevem as formas masculinas; para uma abertura no feminino, ponha o ordinal no modelo do nível e imprima-o com {number}.

Num design de título, {numberWords} / {numberWordsLower} e {numberOrdinalWords} / {numberOrdinalWordsLower} escrevem o contador do título da mesma forma, de modo que a abertura pode dizer Chapter One enquanto o sumário mostra 1. O textTransform: 'uppercase' de um elemento de texto dá as maiúsculas:

// Romance em espanhol: "CAPÍTULO PRIMERO" acima do título, "1." no sumário.
{ level: 1, numberingTemplate: '{1}.', span: 'page',
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'n', content: 'Capítulo {numberOrdinalWordsLower}', textTransform: 'uppercase', /* … */ },
    { kind: 'text', id: 't', content: '{titleText}', /* … */ },
  ] } } }

#Listas com marcadores

A propriedade unorderedLists controla como são renderizadas as listas com marcadores (-, *, +) e as listas de tarefas do GFM (- [ ], - [x]). São aceitos até cinco níveis de aninhamento.

#Padrões das listas com marcadores

#Extensões para listas de tarefas

Os itens de tarefa do GFM (- [ ] …, - [x] …) são renderizados como itens com marcador, com um glifo de caixa de seleção no lugar do marcador. Os campos a seguir se aplicam só aos itens de tarefa:

#Substituições por nível (listas com marcadores)

Cada entrada de levels se refere a uma profundidade (1–5) e pode substituir qualquer um dos seguintes:

Cascata de recuos. O nível 1 sempre começa no valor geral de indent (por padrão 0 em: os marcadores ficam presos à borda da coluna). Nos níveis 2–5, se você deixar indent indefinido, o motor põe o marcador no início do texto do nível anterior (recuo do pai + largura do marcador + gap). Defina um indent explícito num nível para interromper a cascata e fixar essa profundidade onde quiser.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Listas numeradas

A propriedade orderedLists controla as listas numeradas (1., 2) etc.). São aceitos até cinco níveis de aninhamento, e cada profundidade pode usar um formato de número diferente.

#Padrões das listas numeradas

#Substituições por nível (listas numeradas)

Cada entrada de levels pode substituir numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset e o estilo do separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap); vale a mesma cascata de recuos das listas com marcadores. O estilo do separador de um nível herda o estilo do número desse mesmo nível, a menos que a configuração do separador para a lista inteira seja informada.

Alinhamento à direita. O pipeline mede o número formatado mais largo de uma sequência e recua todos os itens dessa sequência para que os números se alinhem pela borda direita. Numa lista de dez itens renderizada como 1. – 10., os números de um dígito recebem preenchimento à esquerda para que o separador fique na mesma coluna.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

Isso produz a mistura aninhada clássica:

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

A hierarquia dos documentos chineses (GB/T 15834—2011, Anexo B.3) tem cinco níveis: 一、, depois （一）, depois 1., depois （1） e depois ①:

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#Matemática

A propriedade math controla como são analisadas e renderizadas as fórmulas LaTeX entre os delimitadores $...$ (em linha) e $$...$$ (em destaque). O motor por trás é o MathJax (o pacote mathjax-full) no modo de saída SVG, rasterizado no canvas e incorporado como glifos escaláveis no PDF.

interface MathConfig {
  enabled?: boolean;        // Renderiza o LaTeX. Com false, os trechos passam como TeX literal.
  fontSizeScale?: number;   // × o tamanho do texto ao redor (o tamanho do corpo nas fórmulas em destaque).
  color?: ColorValue;       // Cor das fórmulas; herda a cor do corpo se omitida.
  marginTop?: Dimension;    // Espaço acima dos blocos de fórmula em destaque.
  marginBottom?: Dimension; // Espaço mínimo abaixo; o ajuste à grade de linhas de base pode aumentá-lo.
  indentAfterDisplay?: boolean; // Recua um parágrafo que vem depois de uma fórmula em destaque.
  keepWithLeadIn?: boolean; // Mantém uma fórmula em destaque com a linha que a introduz.
  equationNumbering?: {      // Numera as fórmulas em destaque que levam um \label.
    enabled?: boolean;           // padrão true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numera por capítulo
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': o que a fórmula e \eqref imprimem
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Tamanho das fórmulas, alterado no postext 1.5. O MathJax dá a caixa de uma fórmula em ex, e um ex da sua fonte TeX equivale a 0,442 em. Até o postext 1.4 o motor o tomava como meio em, de modo que toda fórmula era composta cerca de 13% maior que bodyText.fontSize × fontSizeScale. Agora as fórmulas saem no tamanho documentado, e as linhas e páginas com fórmulas são recompostas. Uma configuração escrita em código para a 1.4 mantém o tamanho de fórmula da 1.4 se passar por pinLegacyMathSize, de postext/bundle, uma única vez, tal como foi escrita:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // as fórmulas, e o espaço em volta das fórmulas em destaque, como a 1.4 as compunha

Outras mudanças de regras na 1.5 também podem mexer nas suas páginas: as quebras dos títulos, o espaço em volta de uma figura em linha (no texto corrido e nos boxes), as marcas em linha dos seus títulos, o tamanho das suas capitulares, o espaço reservado sob uma linha terminada em dois-pontos para a lista que ela introduz, as linhas que o corte de um boxe deixa de um parágrafo ou de um item de lista, as quebras de linha depois de um travessão, a quebra do texto em bandeira, a divisão de um parágrafo sob um título, as quebras de linha depois do hífen de uma palavra composta e o espaço sob um contêiner :::paragraphs. migrateConfig, executado uma vez com o markdown que a configuração diagrama, fixa as que esse texto precisa, o tamanho das fórmulas incluído (veja Pacotes escritos pelo postext 1.4 ou anterior):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // quebras de títulos, fórmulas, espaços em linha, marcas de títulos, capitulares, linhas com dois-pontos, cortes de boxes, quebras após travessão, quebras de compostos, texto em bandeira, divisões sob um título e espaço dos contêineres como a 1.4 os compunha

Isso segura o que essas mudanças de regras moveriam, mas não preserva todas as páginas da 1.4. A versão 1.5 também corrige bugs de layout, e uma correção não tem fixação: uma configuração antiga a recebe como uma nova, então uma página afetada por ela ainda pode mudar. Entre elas: um título na largura da página sem design próprio é medido na largura da página e composto na entrelinha do seu nível; nada é reservado sob a linha de base de uma capitular num design de título; uma capitular toma a cor de paleta da seção e é composta mesmo num texto de design cujo overflow não é 'wrap', que então quebra linhas; um parágrafo num boxe pinta o tracking com que foi medido; um boxe dividido mantém a coluna do ícone em todos os fragmentos; uma linha de boxe que esticaria os espaços além de 3× é composta em bandeira, como no texto corrido; o recurso de parágrafo frouxo nunca compõe uma linha justificada mais larga do que maxWordSpacing permite; um boxe flutuante mantém uma marginBottom (numa faixa superior) ou uma marginTop (numa faixa inferior) maior que o espaço entre flutuantes; um texto de design centralizado ou alinhado à direita com tracking (um cabeço, o título de uma abertura) é posicionado pelas suas letras, sem o tracking depois da última; sob uma abertura na largura da página, o texto que abre a segunda coluna começa onde começaria o texto logo abaixo da abertura, também quando um título segue a abertura; os pontos do sumário param antes do número de página numa fonte cujo kerning afasta uma sequência de pontos; um cabeço lê um título tal como foi escrito, sem espaço onde uma das suas linhas termina depois de um hífen ou de um travessão ou dentro de uma palavra cortada por largura (MEDIOAMBIENTALES, não MEDIOAMBIENTALE S), e o {titleText} de um design de título o lê do mesmo jeito (thousand-colour, não thousand- colour); um texto ancorado no pé ou no meio da faixa de um design de título mantém a faixa alta o bastante para contê-lo, de modo que ele não sobe mais sobre o texto acima do título; uma palavra mais larga que a sua linha, cortada junto a um hífen que ela própria tem, é cortada depois desse hífen e não recebe um segundo; o item depois de uma lista aninhada noutra recebe o itemSpacing da sua própria lista, não o da lista aninhada; e o resto de uma palavra cortada por ser mais larga que a sua linha mantém os seus próprios pontos de quebra, de modo que um endereço web continua quebrando nas suas junções, e uma palavra composta nos seus hifens, em vez de nas sílabas do dicionário.

pinLegacyMathSize multiplica a escala por 1,1312 (0,5 ÷ 0,442) e divide pelo mesmo fator as margens das fórmulas em destaque em em. Só a escala não basta para um livro com fórmulas em destaque: as margens delas são medidas do tamanho da própria fórmula, então cresceriam os mesmos 13% e empurrariam para baixo o texto abaixo delas. Escritos por extenso para as margens padrão, os três valores são:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // fórmulas do tamanho que a 1.4 compunha, com o espaço que a 1.4 deixava em volta

Quando se sabe onde a configuração estava guardada, o motor faz isso por você: openBundle / readBundle num pacote .postext escrito antes da 1.5 (veja Pacotes escritos pelo postext 1.4 ou anterior), e o Sandbox nos livros, na cópia de trabalho e nos arquivos postext-config.json salvos naquela época (veja Sandbox → Persistência). Eles são lidos por meio de migrateConfig, que fixa o tamanho (pinLegacyMathSize): fontSizeScale passa a ser a escala guardada (1 quando não definida) × 1,1312, e uma margem de fórmula em destaque em em ou rem (uma medida do tamanho da própria fórmula) é dividida pelo mesmo fator, de modo que o espaço em volta de uma fórmula em destaque fica como a 1.4 o deixava (os 0,8 em padrão passam a 0,7072 em). Uma margem numa unidade de página (pt, mm…) fica como está, assim como uma configuração com enabled: false ou uma cujo livro não tem nenhum $. O livro antigo é então diagramado como a 1.4 o diagramava, e a sua seção math mostra o tamanho em que é composto. Para compor esse livro no tamanho atual, redefina esses valores: Fórmulas → Escala de tamanho, Margem acima (destaque) e Margem abaixo (destaque) no Sandbox, ou em código:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // tamanho e margens atuais

Equações numeradas. Uma fórmula em destaque com número ocupa a sua medida (a coluna, ou a largura interna do boxe em que está): a equação fica centralizada e o seu número, alinhado à direita na linha da equação, em cada linha numerada de um align. O número vem de um \label{eq:x} (desde o postext 1.19): as fórmulas rotuladas, e as linhas rotuladas de um align, gather, alignat, flalign ou eqnarray, são numeradas em ordem de leitura com equationNumbering, a menos que uma linha diga \nonumber ou \notag. Ambientes como equation não são numerados por si sós: uma fórmula sem rótulo não tem número. \tag{…} imprime o rótulo que você der, entre parênteses, e \tag*{…}, tal como foi escrito; nenhum dos dois é contado, e um \label ao lado de um deles lhe dá um nome. Uma equação numerada mais larga que a sua medida transborda para a direita, como qualquer fórmula em destaque. (Até o postext 1.4 uma fórmula com \tag não era desenhada; até a 1.18 só \tag numerava uma fórmula.)

\eqref{eq:x} no texto imprime o número no seu format, (3), e \ref{eq:x}, o número sozinho; o mesmo fazem :ref{id="eq:x"} e @eq:x (veja Referências cruzadas), e dentro de uma fórmula \eqref o imprime como texto. Num livro diagramado capítulo por capítulo, o contador continua a partir do capítulo anterior: continuationAfter o leva em LayoutContinuation.statementCounters (equation), e o esboço do livro dá a cada rótulo o seu número (OutlineEntry.numberLabel), de modo que uma referência a uma equação de outro capítulo a imprime.

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

O resolvedor e o redutor seguem o padrão das outras seções:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#Inicializar o motor de fórmulas

O MathJax é carregado sob demanda, não junto com o resto do motor. Quando você diagrama na thread principal, inicialize-o antes de construir um documento que tenha fórmulas:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // carrega o MathJax uma vez; as chamadas seguintes resolvem na hora
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Até o motor rodar, as fórmulas são marcadores de posição. Cada uma é diagramada como uma caixa cinza de tamanho estimado. Se um documento com fórmulas for diagramado sem que initMathEngine() tenha sido chamado alguma vez, o console mostra um aviso dizendo isso.
• O worker de layout o inicializa por você. Uma construção em postext/worker chama initMathEngine() por conta própria quando o markdown contém um $.
• Diagramar agora e de novo quando estiver pronto. isMathReady() diz se o motor está rodando. onMathReady(fn) chama fn assim que ele estiver (na hora, se já estiver) e devolve uma função que cancela a chamada. Um editor pode mostrar os marcadores de posição de imediato e diagramar de novo quando o MathJax chegar; nenhum aviso é impresso enquanto initMathEngine() está em andamento.
• Falha. initMathEngine() rejeita quando o MathJax não pode ser carregado, e uma chamada posterior tenta de novo.
• Qualquer bundler, Node ou uma CDN. O MathJax vem dentro do pacote como um único módulo pré-empacotado (cerca de 1,8 MB antes da compressão, baixado só por initMathEngine). O simples import { initMathEngine } from 'https://esm.sh/postext' funciona; não é preciso ?bundle. O pacote mathjax-full só é necessário para compilar o postext, então instalar o postext não o instala. O MathJax e o analisador mhchem que ele inclui têm licença Apache-2.0: os avisos deles e o texto da licença acompanham o módulo, em dist/math/THIRD_PARTY_LICENSES.txt.
• Um motor por página. O motor e o seu cache de fórmulas renderizadas são compartilhados por tudo o que importa postext no mesmo realm JavaScript (veja Estado global compartilhado numa página).

Para a gramática do lado do documento ($...$, $$...$$, como escapar um cifrão literal), veja Formato do documento.

#Notas de rodapé

A propriedade footnotes define onde ficam as notas citadas com [^id], como são numeradas e qual é a sua aparência. A marcação é descrita em Formato do documento.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // No pé da coluna que cita, depois do capítulo, ou ao lado do texto de uma página dupla.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Recomeça a cada capítulo, segue corrida, ou recomeça a cada página / coluna / página dupla.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // Os símbolos de nota de numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Elevado, na linha de base, ao lado da palavra, ou à direita de uma linha vertical.
  markerSize?: Dimension;     // Tamanho do marcador em linha, lateral ou à direita; em é o texto ao redor.
  numberGap?: 'en' | 'em';    // Espaço depois do número da própria nota.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notas no pé da coluna ou logo abaixo do texto.
  fontSize?: Dimension;       // Tamanho das notas; em é o tamanho do corpo.
  lineHeight?: Dimension;     // Entrelinha das notas; em é o tamanho da nota.
  color?: ColorValue;         // Cor das notas; a cor do corpo quando não definida.
  textAlign?: TextAlign;      // O alinhamento do corpo quando não definido.
  hangingIndent?: Dimension;  // Recuo das linhas seguintes de uma nota.
  spaceBetween?: Dimension;   // Espaço entre duas notas.
  spaceAbove?: Dimension;     // Espaço entre o texto e o fio; em é o tamanho do corpo.
  spaceBelowRule?: Dimension; // Espaço entre o fio e a primeira nota.
  separator?: {
    enabled?: boolean;        // Desenha o fio.
    width?: number;           // Comprimento do fio, uma fração da largura da coluna.
    lineWidth?: Dimension;    // Espessura do fio.
    color?: ColorValue;       // A cor das notas quando não definida.
  };
}