# Configuração: notas e referências

> As notas de rodapé, a numeração de linhas, as referências cruzadas e as citações, o sumário e o índice remissivo

- Versão HTML: https://postext.dev/pt/docs/configuration-notes-references
- Última atualização: 2026-10-10
- Tempo de leitura: 4 min
- Outros idiomas: [en](https://postext.dev/en/docs/configuration-notes-references.md), [es](https://postext.dev/es/docs/configuration-notes-references.md), [ca](https://postext.dev/ca/docs/configuration-notes-references.md), [zh](https://postext.dev/zh/docs/configuration-notes-references.md), [ja](https://postext.dev/ja/docs/configuration-notes-references.md), [ar](https://postext.dev/ar/docs/configuration-notes-references.md)

## Em poucas palavras

Esta página reúne os ajustes das partes do livro que remetem a outro lugar. As notas ficam no pé da página e os números de linha ficam na margem. As referências cruzadas indicam uma figura, uma seção ou uma página, e as citações indicam as obras que você menciona. O sumário lista os capítulos e o índice remissivo, no fim, lista termos com suas páginas. Cada seção explica a aparência dessas peças e como elas são numeradas.

## 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](https://postext.dev/pt/docs/document-format.md#notas-de-rodapé).

```ts
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.
  };
}
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `placement` | `'column' \| 'chapterEnd' \| 'spread'` | `'column'` (livros japoneses em escrita vertical: `'chapterEnd'`) | `'column'` compõe cada nota no pé da coluna que contém a linha que a cita, sob um fio curto; num layout de uma coluna, é o pé da página. `'chapterEnd'` compõe todas as notas de um capítulo depois do seu último bloco, em ordem de citação. `'spread'` (傍注, só texto vertical) compõe as notas citadas nas duas páginas de uma página dupla no fim da sua página ímpar, a página da esquerda de um livro com lombada à direita, sob o fio: as notas citadas na página par esperam por ela; uma nota que deixaria a página ímpar com menos de uma linha de texto fica no pé da página par, com as que vêm depois dela; e um capítulo que termina numa página par mantém ali as notas que estavam esperando. Em texto horizontal recai em `'column'`, com um aviso `unknownConfigValue`. Desde o postext 1.16. |
| `numbering` | `'chapter' \| 'document' \| 'page' \| 'column' \| 'spread'` | `'chapter'` (livros japoneses em escrita horizontal: `'page'`; com `placement: 'spread'`: `'spread'`; com `numberFormat: 'symbols'` no pé da coluna: `'page'`) | `'chapter'` recomeça em 1 sob cada título de nível 1 e no início de cada documento. `'document'` segue corrida pelo documento e, num livro diagramado capítulo por capítulo, de um capítulo para o seguinte (`continuationAfter` leva o último número como `continuation.footnoteNumber`). `'page'` recomeça em 1 a cada página e `'column'` a cada coluna, contando as notas onde o layout as compõe (as colunas de uma página em ordem de leitura): o habitual 页下注 de um livro chinês. O documento é diagramado, numerado onde as suas notas caíram e diagramado de novo até os números se manterem (no máximo três construções a mais). Os dois se aplicam a notas no pé da coluna: com `placement: 'chapterEnd'` as notas são numeradas por capítulo. `'spread'` recomeça a cada página dupla (páginas 2–3, 4–5…), em ordem de citação, para `placement: 'spread'`. |
| `numberFormat` | `string` | `'decimal'` | Como os números são escritos, em qualquer grafia que as configurações de numeração aceitam: `'decimal'`, `'lower-roman'`, `'lower-alpha'`, `'circled-decimal'` (ou `'①'`), `'cjk-decimal'`, `'一'`… O marcador e o número que abre a nota usam esse formato. `circled-decimal` escreve em decimal os números acima de 50. Um nome desconhecido numera em decimal, com um aviso `unknownNumberFormat`. `'symbols'` (ou `'*'`) marca as notas com símbolos de referência, `symbols` em sequência: * † ‡ § ‖ ¶, depois dobrados (** †† ‡‡…) e triplicados; as notas são então contadas de novo a cada página, a menos que `numbering` seja definido. Desde o postext 1.19. |
| `symbols` | `string[]` | `['*', '†', '‡', '§', '‖', '¶']` | A sequência que `numberFormat: 'symbols'` escreve, dobrada e depois triplicada quando se esgota. Os arquivos latinos do Google Fonts e do Fontsource trazem * † § ¶ (a adaga em `latin-ext`), mas não ‡ nem ‖, que o PDF então desenha como o glifo `.notdef` da fonte, com um aviso `missingGlyph`: com uma fonte assim, deixe-os de fora (`['*', '†', '§', '¶']`) ou componha as notas numa fonte que os tenha. Strings vazias são descartadas, e uma lista vazia mantém o padrão. Desde o postext 1.19. |
| `markerPosition` | `'auto' \| 'superscript' \| 'inline' \| 'side' \| 'right'` | `'auto'` | `'superscript'` eleva o marcador no texto e o número que abre a nota, em tamanho reduzido. `'inline'` os compõe na linha de base: o marcador em `markerSize`, o número da nota no tamanho da nota; em texto vertical, um marcador circulado em linha fica em pé numa célula própria. `'right'` compõe um marcador reduzido rente ao lado direito de uma linha vertical, como os livros japoneses verticais compõem （1）; em texto horizontal é um sobrescrito. `'side'` (合印) compõe um marcador pequeno ao lado da palavra marcada, do lado do seu rubi, terminando onde termina o último caractere da palavra; não ocupa espaço na linha, que quebra e justifica como se ele não estivesse ali, e um espaço entre linhas estreito demais para ele é relatado como `rubyExceedsLeading`. `'auto'` é em linha para `circled-decimal`, `'right'` num livro japonês vertical e sobrescrito nos demais casos. De qualquer forma, o marcador fica junto do caractere anterior e nunca abre uma linha. |
| `markerSize` | `Dimension` | `1em`; `0.6em` para `'side'`, `0.7em` para `'right'` | Tamanho de um marcador em linha, lateral ou à direita; `em` é o tamanho do texto ao redor (`0.75em` é uma redução comum). Sem efeito num marcador sobrescrito. |
| `numberGap` | `'en' \| 'em'` | `'en'` (notas japonesas depois do capítulo: `'em'`) | O espaço depois do número que abre uma nota: um espaço meia-risca ou um eme inteiro da nota (um espaço ideográfico quando o número ou a nota contém texto CJK), nunca esticado nem quebrado. Desde o postext 1.16. |
| `markerTemplate` | `string` | `'{n}'` (livros japoneses em escrita vertical: `'（{n}）'`) | Como se escreve o número de uma nota, com `{n}` no lugar dele, no formato de número e nos algarismos do documento: `'({n})'` dá os marcadores entre parênteses dos livros árabes, «(١)». Escreve tanto o marcador no texto quanto o número que abre a nota. Um modelo sem `{n}` é lido como o padrão. |
| `noteNumberPosition` | `'auto' \| 'superscript' \| 'inline'` | `'auto'` | Onde fica o número que abre a nota: elevado ou na linha, no tamanho da nota. `'auto'` segue `markerPosition`. Os livros árabes elevam o marcador no texto e compõem o número da própria nota na linha. |
| `chapterEndAlign` | `'foot' \| 'text'` | `'foot'` | Com `placement: 'chapterEnd'`: `'foot'` compõe no pé da coluna as notas que a fecham, com as linhas que sobram entre o texto e as notas, como ficam as notas no pé da coluna. `'text'` as compõe logo abaixo do texto. |
| `fontSize` | `Dimension` | `0.8em` | Tamanho do texto das notas. `em` e `rem` são o tamanho do corpo. As notas usam a família e os pesos do corpo. |
| `lineHeight` | `Dimension` | `1.25em` | Entrelinha do texto das notas; `em` é o tamanho da nota. As notas ficam fora da grade de linhas de base: elas se empilham a partir do pé da coluna, e o texto acima delas continua na grade. |
| `color` | `ColorValue` | cor do corpo | Cor do texto das notas. |
| `textAlign` | `TextAlign` | alinhamento do corpo | Alinhamento do texto das notas. |
| `hangingIndent` | `Dimension` | `0` | Recuo da segunda linha em diante de uma nota, para que se alinhem depois do seu número. |
| `spaceBetween` | `Dimension` | `0` | Espaço entre duas notas. |
| `spaceAbove` | `Dimension` | `0.5em` | Espaço entre a última linha do texto e o fio; `em` é o tamanho do corpo. Com `'chapterEnd'` e `chapterEndAlign: 'text'`, `spaceAbove` + `spaceBelowRule` é o espaço entre o texto e a primeira nota. |
| `spaceBelowRule` | `Dimension` | `0.4em` | Espaço entre o fio e a primeira nota. |
| `separator.enabled` | `boolean` | `true` | Desenha o fio acima das notas de cada coluna. Com `false`, os espaços acima continuam. |
| `separator.width` | `number` | `0.3` | Comprimento do fio como fração da largura da coluna (0–1), a partir da borda esquerda da coluna. |
| `separator.lineWidth` | `Dimension` | `0.5pt` | Espessura do fio. |
| `separator.color` | `ColorValue` | cor das notas | Cor do fio. |

```ts
footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}
```

**Livros japoneses.** Um documento japonês (`locale: 'ja'`, desde o postext 1.16) dá aos campos que deixa sem definir os valores do JLReq §4.2. Um livro vertical compõe as notas depois do capítulo (`placement: 'chapterEnd'`, 後注), numeradas por capítulo, com marcadores `（{n}）` à direita da linha (`markerPosition: 'right'`, algarismos em pé por `cjk.uprightDigits`); um horizontal as compõe no pé da página, numeradas por página, com marcadores sobrescritos. Os dois desenham o fio com um terço da medida (`separator.width: 1/3`), e as notas depois do capítulo recebem `numberGap: 'em'` e um recuo deslocado de dois emes. Um valor explícito prevalece e é mantido ao salvar (`stripFootnotesDefaults` compara com os padrões do próprio documento); documentos em chinês, árabe e línguas latinas se resolvem como antes. `footnoteDocumentDefaults(locale, writingMode, placement?)` devolve esses valores. Escreva o marcador antes de um 。 de fim de frase (`先生[^1]。`): ele fica junto do caractere anterior, e 。 nunca abre uma linha. Veja [Composição em japonês › Notas](https://postext.dev/pt/docs/japanese-layout.md#notas).

Como as notas são compostas no pé da coluna:

- **Nota e citação dividem uma coluna.** Antes de posicionar uma linha, o layout soma a altura das notas que essa linha cita pela primeira vez (e o fio, na primeira nota da coluna). Uma linha cujas notas não cabem abaixo dela vai para a coluna seguinte com o resto do seu parágrafo, conforme as regras de órfãs e viúvas. A área de texto da coluna diminui na altura das notas, então o balanceamento de colunas e a faixa final de um capítulo contam só o texto.
- **Várias notas** numa coluna se empilham em ordem de citação sob um único fio. Uma nota citada de novo mais adiante mantém o seu número e não é composta outra vez.
- **Flutuantes inferiores.** Uma figura que ocupa o pé de uma coluna depois que as notas dela foram compostas fica acima delas; as notas compostas depois da figura ficam acima dela.
- **Boxes.** Uma nota citada dentro de um boxe (em linha, flutuante ou fixo) vai para o pé da coluna em que o texto depois do boxe continua, em geral a mesma coluna. Um boxe que fecha o documento deixa as suas notas no pé da coluna em que o texto terminou.
- **Limites.** Uma nota nunca é dividida: uma nota mais alta que uma coluna transborda dela. Os marcadores em legendas, células de tabela e títulos não são lidos (saem impressos como foram escritos).
- **Saída.** Canvas, HTML e PDF pintam as notas, os marcadores (um número sobrescrito) e o fio. No PDF cada marcador tem um link para a sua nota, e um PDF etiquetado compõe cada nota como um elemento `Note` com um `/ID` único listado na `/IDTree` da árvore de estrutura (PDF/UA-1). As notas são `VDTBlock`s com `footnoteNote` definido, em `page.floats`; os fios ficam em `page.footnoteAreas`.
- **Avisos.** `undefinedFootnote` (um marcador sem definição: o número é impresso sobre uma nota vazia) e `unusedFootnote` (uma definição que nenhum marcador cita: não é composta).

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

```ts
import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';

resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // os campos não definidos recebem os padrões japoneses verticais
```

## Numeração de linhas

A propriedade `lineNumbers` imprime na margem o número de cada quinta linha (ou de cada enésima), ao lado dela, como fazem as edições críticas, as antologias de poesia, os textos legais e as edições escolares. Ela conta os versos dos poemas `:::verse`, ou todas as linhas do texto. Vem desligada por padrão. Cada número é pintado na linha de base da sua linha, num corpo próprio, e nunca move uma linha: a página é diagramada exatamente como seria sem números. Desde postext 1.23.

```ts
interface LineNumbersConfig {
  enabled?: boolean;        // Desligada por padrão.
  count?: 'verse' | 'all';  // Os versos dos poemas, ou todas as linhas do texto.
  interval?: number;        // Imprimir os múltiplos de N.
  numberFirst?: boolean;    // Imprimir também a primeira linha depois de cada reinício.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // Onde a contagem recomeça.
  startAt?: number;         // O número da primeira linha depois de um reinício.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // Páginas com duas colunas ou mais.
  gap?: Dimension;          // Do texto ao número; em é o corpo do número.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // A família do texto corrido quando não definida.
  fontSize?: Dimension;     // em é o corpo do texto.
  fontWeight?: number;      // O peso do texto corrido quando não definido.
  italic?: boolean;
  color?: ColorValue;       // A cor do texto corrido quando não definida.
  format?: string;          // decimal, lower-roman, arabic-indic, 一…
}
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `false` | Imprime os números de linha. Um documento vertical (`layout.writingMode: 'vertical-rl'`) não recebe nenhum, e um `true` nele é avisado como `lineNumbersUnsupported`. |
| `count` | `'verse' \| 'all'` | `'verse'` | `'verse'` conta os versos dos poemas `:::verse`, cada verso uma vez: a parte de um verso longo demais para a mancha que passa para a linha seguinte não recebe número, e o espaço entre estrofes não é contado. Um poema na disposição árabe clássica conta uma linha por bayt; a segunda linha de um bayt composto em escada não é contada. `'all'` conta todas as linhas dos parágrafos do texto corrido, dos itens de lista, das citações e dos versos, em ordem de leitura: página por página, coluna por coluna, de cima para baixo. |
| `interval` | `number` | `5` | Imprime o número de cada linha que é múltiplo deste (5, 10, 15…). Um poema cujo primeiro verso é o 37 imprime 40, 45… A abertura de um poema pode definir o seu (`interval=N`). |
| `numberFirst` | `boolean` | `false` | Imprime também o número da primeira linha contada depois de cada reinício. |
| `restart` | `'document' \| 'chapter' \| 'section' \| 'page' \| 'poem'` | `'poem'` com `count: 'verse'`, `'page'` com `count: 'all'` | Onde a contagem recomeça: nunca (`'document'`, que segue por todos os capítulos de um livro), a cada título de nível 1 (`'chapter'`), a cada título de nível 1 ou 2 (`'section'`), a cada página (`'page'`) ou a cada poema `:::verse` (`'poem'`). O `lineStart=N` de um poema e o `lines=N` da diretiva `:::numbering` a reiniciam em qualquer ponto, seja qual for o modo. |
| `startAt` | `number` | `1` | O número da primeira linha depois de um reinício. |
| `position` | `'outer' \| 'inner' \| 'left' \| 'right' \| 'start' \| 'end' \| 'side'` | `'outer'` | O lado em que ficam os números. `'outer'` é o lado oposto à lombada: a direita de uma página ímpar e a esquerda de uma par, ao contrário num livro encadernado pela direita. `'inner'` é o lado da lombada. `'left'` e `'right'` são o mesmo em todas as páginas. `'start'` e `'end'` seguem a direção do documento: `'start'` é a direita num livro da direita para a esquerda. `'side'` os coloca na coluna lateral de um layout `'oneAndHalf'` com `layout.sideColumnRole: 'floats'`, encostados à borda da coluna lateral voltada para o texto (`gap` não é usado); numa página sem coluna lateral volta a `'outer'`. |
| `multiColumn` | `'each' \| 'gutter' \| 'outer-edges'` | `'outer-edges'` | Páginas com duas ou mais colunas de texto lado a lado. `'outer-edges'` põe os números da primeira coluna à esquerda dela e os da última à direita dela; as colunas do meio seguem `'each'`. `'gutter'` os põe nas medianizes: os da primeira coluna à direita dela, os das outras à esquerda delas. `'each'` põe os de cada coluna no lado de `position`. |
| `gap` | `Dimension` | `1em` | A distância da borda da coluna até o número; `em` é o corpo do próprio número. |
| `align` | `'auto' \| 'left' \| 'right'` | `'auto'` | `'auto'` alinha cada número em direção ao texto: à direita numa margem esquerda, à esquerda numa margem direita. `'left'` e `'right'` alinham os números dentro da largura do número mais largo da página. |
| `fontFamily` | `string` | família do texto corrido | Fonte dos números. É carregada e incorporada como qualquer outra família. |
| `fontSize` | `Dimension` | `0.8em` | Corpo dos números; `em` é o corpo do texto. |
| `fontWeight` | `number` | peso do texto corrido | Peso dos números. |
| `italic` | `boolean` | `false` | Compõe os números em itálico. |
| `color` | `ColorValue` | cor do texto corrido | Cor dos números. Uma cor ligada à paleta segue as paletas de partes e seções. |
| `format` | `string` | decimal | Como os números são escritos, em qualquer das [grafias dos formatos de numeração](https://postext.dev/pt/docs/configuration-page-layout.md#grafias-dos-formatos-de-numeração) (`'lower-roman'`, `'arabic-indic'`, `'一'`…). Os números decimais são escritos com os algarismos do documento (`numerals`). Um nome desconhecido numera em decimal, com um aviso `unknownNumberFormat`. |

```ts
lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // uma só contagem para o livro inteiro
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}
```

O que é contado e o que não é:

- **Nunca são contados** os títulos, as legendas, as tabelas e as imagens, as fórmulas em destaque, o texto de design (aberturas, cabeços), as notas de rodapé e as notas de fim de capítulo, o sumário, as entradas do índice remissivo e da bibliografia, nem as páginas em branco.
- **Boxes e prosa.** O texto de um boxe não é contado, e com `count: 'verse'` a prosa também não, a menos que o estilo de parágrafo em que é composta diga `lineNumbers: true`; um estilo com `lineNumbers: false` nunca é contado (veja [Estilos de parágrafo](https://postext.dev/pt/docs/configuration-styles.md#estilos-de-parágrafo)).
- **Um poema.** A abertura de um poema aceita `numbered=false` (os seus versos não são contados), `lineStart=N` (o seu primeiro verso é o N, e a contagem recomeça ali) e `interval=N`. `:::numbering{lines=N}` dá o número N à próxima linha contada, onde quer que esteja. Veja [Formato do documento › `:::verse`](https://postext.dev/pt/docs/document-format.md#verse) e [`:::numbering`](https://postext.dev/pt/docs/document-format.md#numbering).

Num livro diagramado capítulo por capítulo, `restart: 'document'` leva a contagem de um capítulo para o seguinte em `continuation.lineNumber`. `continuationAfter` conta os versos a partir do texto; com `count: 'all'` a contagem depende da diagramação, então a aplicação repassa o `lastLineNumber` do documento do capítulo anterior, como faz o Sandbox.

Com `position: 'side'` os números dividem a coluna lateral com os boxes, as legendas e as figuras laterais. Um número que se sobrepõe a um deles é pintado mesmo assim, nenhum dos dois se move, e a diagramação dá um aviso de conteúdo `lineNumberOverlap` que aponta para a linha numerada.

**Saída.** Canvas, PDF, o visualizador HTML e o EPUB de layout fixo pintam os números. Num PDF etiquetado eles são artefatos de paginação e cada um leva um `/ActualText` vazio, de modo que o texto copiado ou extraído passa de uma linha para a outra sem eles. A saída HTML os esconde das tecnologias assistivas (`aria-hidden`), da seleção e do texto copiado. O EPUB refluível, cujas linhas são compostas pelo sistema de leitura, guarda só os números dos versos: um `span` `pt-line-number` (também `aria-hidden`) na margem inicial da estrofe, ao lado de cada verso que leva número na versão impressa. No VDT os números são um bloco de design de cada página (`page.lineNumbers`, com os blocos de texto marcados `artifact`) e uma lista de marcas (`page.lineNumberMarks`: `number`, `label`, `columnIndex`, `blockId`, `lineIndex`); o documento registra `lastLineNumber`.

**Não há suporte** para números de linha em texto vertical, uma referência cruzada que imprima o número de uma linha, notas ligadas a números de linha, nem números para as linhas de células de tabela, legendas ou listagens de código.

No Sandbox essas configurações são a seção **Numeração de linhas** do painel Design. O resolvedor e o removedor de padrões seguem as outras seções; a fonte, o peso e a cor vêm do texto corrido:

```ts
import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';

resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // fonte, peso e cor não definidos seguem o texto corrido
```

## Referências cruzadas

A propriedade `crossRefs` define as palavras que uma [referência cruzada](https://postext.dev/pt/docs/document-format.md#referências-cruzadas-e-âncoras) imprime em volta de um número ou de uma página, e o estilo que um `:ref` assume quando não define nenhum. Cada modelo contém `{n}` onde vai o número; um modelo sem ele recebe o número depois de um espaço inseparável (`"§"` imprime *§ 3.2*). Um modelo não definido segue o idioma do documento: *chapter / section / p.* em inglês, *capítulo / sección / pág.* em espanhol, `第{n}章` / `第{n}节` / `第{n}页` em chinês, e assim por diante em francês, alemão, italiano, português, catalão e neerlandês.

```ts
interface CrossRefsConfig {
  chapter?: string;  // Palavras em volta do número de um título de nível 1: "chapter {n}".
  section?: string;  // Em volta do número de qualquer outro título: "section {n}".
  page?: string;     // Em volta de um número de página: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // Um :ref sem style=.
}
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `chapter` | `string` | conforme o idioma | Uma referência a um título de nível 1: `"chapter {n}"`. O número de um título cujo modelo já escreve a palavra (`Chapter {1}`, `第{1:一}章`) é impresso como está. |
| `section` | `string` | conforme o idioma | Uma referência a um título de nível 2 a 6: `"section {n}"`, `"§ {n}"`. |
| `page` | `string` | conforme o idioma | Uma referência de página (`style=page`): `"p. {n}"`, `"page {n}"`. |
| `defaultStyle` | `'default' \| 'number' \| 'title' \| 'page'` | `'default'` | O que um `:ref` a um título ou a uma âncora imprime sem `style=`. `'default'`: um título numerado, pela sua palavra e número; um não numerado, pelo seu título; uma âncora, pelo seu texto. Uma referência que define `style` o mantém, e as referências a figuras e tabelas não são afetadas. |

As referências recebem a cor, o peso e a inclinação de todas as referências (`bodyText.referenceColor`, `referenceBold`, `referenceItalic`).

## Citações

A propriedade `citations` escolhe o estilo de citação e a aparência das citações e da bibliografia. A marcação é descrita em [Citações e bibliografia](https://postext.dev/pt/docs/document-format.md#citações-e-bibliografia); o estilo é aplicado pelo pacote `postext-citeproc`.

```ts
interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… ou 'custom'
  customStyle?: string;    // um estilo CSL completo (XML .csl), usado com style: 'custom'
  locale?: string;         // locale CSL; o idioma do documento quando não definido
  link?: boolean;          // as citações têm link para as suas entradas
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // não definido: a palavra do idioma do documento; '' ou ' ': nenhum
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `style` | `string` | `'apa'` | O id de um estilo incluído (veja [Estilos](https://postext.dev/pt/docs/document-format.md#estilos)) ou `'custom'`. O estilo decide o que as citações e as entradas dizem: nomes, datas, ordem, pontuação e se as citações são notas. |
| `customStyle` | `string` | — | Um estilo CSL completo, o XML de um arquivo `.csl`, usado quando `style` é `'custom'`. O Sandbox o carrega de um arquivo. |
| `locale` | `string` | idioma do documento | O locale CSL em que o estilo escreve as suas palavras (`en-US`, `es-ES`, `zh-CN`, `zh-TW`, `ja-JP`…). Um documento japonês é lido como `ja-JP`: as citações narrativas unem dois autores com と e abreviam mais autores com ほか. |
| `link` | `boolean` | `true` | Uma citação tem link para a sua entrada na bibliografia (link no PDF, âncora no HTML, clique no Sandbox). |
| `marker` | `'style' \| 'brackets' \| 'parentheses' \| 'superscript' \| 'corner'` | `'style'` | Como um estilo numérico marca uma citação: como o estilo a escreve, `[1]`, `(1)`, um sobrescrito ou `〔1〕` (em pé no texto vertical). Um localizador vem depois do número. |
| `collapseRanges` | `boolean` | `true` | Números consecutivos como intervalo: `1–3` num marcador próprio, `[2]–[4]` no do IEEE. `false` os mantém separados. |
| `notes` | `'footnote' \| 'warichu'` | `'footnote'` | Onde um estilo de notas compõe as suas citações: notas de rodapé (posicionadas e numeradas como `footnotes` diz) ou notas em duas linhas dentro da linha (夹注). |
| `numbering` | `'book' \| 'chapter'` | `'book'` | Citações ao longo do livro, ou cada capítulo por si (cada documento, e cada título de nível 1 depois de uma citação): um estilo numérico numera cada capítulo a partir de 1, e uma obra citada em dois capítulos recebe o número de cada capítulo; um estilo de notas escreve uma obra por completo na primeira citação em cada capítulo. Pensado para `bibliography.scope: 'chapter'`, cujas listas então recebem os números do capítulo. |
| `bibliography.title` | `string` | conforme o idioma | Título acima da lista, um parágrafo em negrito. Em branco: nenhum. Um título seu vai acima de `:::bibliography`. |
| `bibliography.scope` | `'book' \| 'chapter'` | `'book'` | Uma lista com todas as obras que o livro cita, ou uma por capítulo com as obras que ele cita. Num documento de vários capítulos, cada H1 inicia uma nova lista de capítulo; com `auto`, um capítulo que não posiciona nenhum `:::bibliography` recebe a sua lista no fim. |
| `bibliography.auto` | `boolean` | `true` | Compõe a lista depois do texto (o último capítulo, numa lista do livro inteiro) quando nenhum `:::bibliography` a posiciona. |
| `bibliography.fontSize` | `Dimension` | `0.9em` | Tamanho das entradas; em é o tamanho do corpo. |
| `bibliography.lineHeight` | `Dimension` | entrelinha do corpo | Entrelinha das entradas. |
| `bibliography.hangingIndent` | `Dimension` | `2em` | Recuo das linhas seguintes de uma entrada não numerada. |
| `bibliography.entrySpacing` | `Dimension` | `0.3em` | Espaço entre duas entradas. |
| `bibliography.labelWidth` | `Dimension` | rótulo mais longo | Largura da coluna em que ficam os números de uma lista numerada: o texto de cada entrada começa a essa distância, tanto na primeira linha quanto nas seguintes, de modo que `9.` e `10.` dividem a coluna. O rótulo continua fazendo parte do texto da entrada. |
| `bibliography.labelAlign` | `'left' \| 'right'` | `'left'` | Onde um rótulo fica na sua coluna: junto à borda esquerda dela ou junto ao texto (`9.` e `10.` terminam juntos). |
| `bibliography.doi` | `'link' \| 'text' \| 'hide'` | `'link'` | DOIs e URLs como links, como texto simples ou omitidos. |
| `bibliography.includeUncited` | `boolean` | `false` | Lista todas as referências, citadas ou não (como `nocite: "@*"`). |
| `bibliography.groupByLanguage` | `boolean` | `false` | As obras em chinês, japonês e coreano primeiro, depois as demais. Só para estilos autor-data e autor-página: uma lista numerada mantém a ordem dos seus números. |

## Sumário

A propriedade `toc` configura o que uma diretiva `:::toc` imprime (veja [Formato do documento](https://postext.dev/pt/docs/document-format.md#toc)). O sumário é montado a partir da **estrutura** do documento (cada título com o seu número e o rótulo da sua página, cada `:::part`), então acompanha os capítulos: renomeie um, mova-o para outra parte, mude os seus autores, e as entradas mudam junto. Uma entrada é o número do título numa coluna própria, o título, uma linha de pontos e o rótulo da página na margem direita, e depois uma linha de subtítulo opcional; uma parte é uma linha desenhada por `parts.design`.

```ts
const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `levels` | `TocLevelConfig[]` | nível 1 | Níveis de título listados, cada um com a tipografia da sua entrada: `fontFamily`, `fontSize`, `lineHeight` (o padrão é a entrelinha do corpo, para o sumário ficar na grade), `fontWeight`, `italic`, `color`, `indent` (da entrada inteira), `numberWidth` / `numberGap` (a coluna do número, depois da qual começa o título; os números ficam alinhados à direita nela, e um número mais largo que `numberWidth`, como `الفصل الحادي عشر` ou `Chapter 12`, alarga a coluna do seu nível até o mais largo), `numberFontFamily`, `numberFontSize`, `numberFontWeight`, `numberColor`, `marginTop`, `marginBottom`. Os campos sem valor herdam do texto do corpo. O número fica na linha de base da primeira linha do título, qualquer que seja a fonte e o corpo, no canvas, no HTML e no PDF (até o postext 1.4 ele ficava centralizado na altura-x como um marcador de lista, e uma fonte display ou um corpo maior ficava acima do título). Um renderizador próprio encontra essa linha de base em `bulletBaselineY` do bloco da entrada; `bulletY` continua sendo o ponto médio da caixa eme do número, como na 1.4, então um renderizador anterior ao novo campo desenha os números onde sempre desenhou. |
| `unnumbered` | `TocEntryStyleConfig` | — | Substituições para títulos cujo estilo tem `numbered: false` (um prefácio): não imprimem número e começam alinhados no `indent` do nível. |
| `pageNumber` | object | fonte do nível 1, peso do corpo | `fontFamily`, `fontSize`, `fontWeight`, `italic`, `color` do rótulo da página, e `width` (padrão `2em`): a coluna reservada para ele na margem direita, onde fica alinhado à direita. |
| `leader` | object | `{ enabled: true, char: '.', gap: 0.5em }` | `char` se repete no espaço entre o título e o número da página, alinhado à direita para que os pontos de entradas seguidas fiquem alinhados (`'. '` os espaça); `gap` é o espaço mínimo mantido entre o título e a linha de pontos. A linha de pontos leva quantos caracteres couberem, medidos como uma sequência inteira na sua fonte, então uma fonte que afasta pontos finais seguidos com kerning recebe menos pontos, em vez de pontos que chegam até o número da página. (Até o postext 1.4 a contagem vinha de um único ponto, e numa fonte assim a linha de pontos corria do título até o número.) Um título que não deixaria espaço para o rótulo quebra um pouco antes. A linha de pontos leva três caracteres ou mais: onde só cabem um ou dois, a linha do sumário fica sem ela, porque um ponto solto antes do número da página se lê como um ponto final. Num PDF com tags, os pontos são artefatos, deixados de fora do texto extraído. O texto do corpo compõe as mesmas linhas de pontos nas suas [paradas de tabulação](https://postext.dev/pt/docs/configuration-text.md#paradas-de-tabulação). |
| `subtitle` | object | `{ enabled: false, attr: 'author' }` | Uma segunda linha sob a entrada, tirada de um atributo do título (`attr`), como os autores do capítulo, com seus próprios `fontFamily`, `fontSize`, `fontWeight`, `italic` (padrão `true`), `color` e `indent` extra. A linha usa a entrelinha da entrada e nunca se separa do seu título. |
| `parts.enabled` | `boolean` | `true` | Se as divisórias de parte recebem uma linha. |
| `parts.breakBefore` | `boolean` | `false` | Abre uma página nova antes de cada linha de parte, exceto a primeira, para que os capítulos de cada parte sejam listados numa página própria. |
| `parts.design` | `DesignSlot` | vazio | Design da linha; o seu contêiner é a linha (largura da coluna × `height`). Marcadores: `{number}`, `{numberDecimal}`, `{numberRoman}`…, `{titleText}` e `{pageNumber}` (o rótulo da página de parte; com `parts.page: false`, que não abre página de parte, o rótulo da página em que começa o conteúdo da parte, onde os cabeços passam a ela; num livro diagramado capítulo a capítulo, um bloco que fecha o seu capítulo aponta para a primeira página de conteúdo do capítulo seguinte). As cores vinculadas à paleta usam a `palette` da própria parte, então a linha de cada seção sai na sua cor. Quando vazio, `{number} {titleText}` (com o `numberSeparator` do H1 entre eles) e o número da página são compostos com a tipografia da entrada de nível 1. |
| `parts.height`, `marginTop`, `marginBottom` | `Dimension` | `2em`, `0`, `0` | Altura da linha e o espaço em volta dela. `em` é o corpo do texto, então a linha padrão tem o dobro do corpo de altura, e não duas linhas do texto: com um texto em 9,5/13,5 pt, ela tem 19 pt. Para uma linha de duas linhas do texto, dê a altura em `pt` (`27pt` nesse caso). |

Os rótulos de página são os que o documento imprime. `buildDocument()` diagrama de novo um documento com `:::toc` usando os rótulos da passada anterior até que eles se estabilizem (no máximo três passadas extras); um host que diagrama um livro capítulo a capítulo fornece em vez disso a estrutura do livro inteiro como `PostextContent.outline`, montada a partir de `contentOutline()` (títulos e partes só a partir do texto) e de `outlineFromDoc()` (as mesmas entradas com os rótulos de página de uma diagramação), e diagrama de novo o capítulo do sumário sempre que o `outlineKey()` dessa estrutura muda. Cada entrada de título traz o `number` que o sumário imprime e, para um título numerado, o seu `counter`: a contagem corrente do nível depois de qualquer `startAt`, seja o que for que o modelo imprima; é o que um host mostra ao lado de um capítulo nas suas próprias listas.

## Índice remissivo

A propriedade `index` configura o que uma diretiva `:::index` imprime (veja [Formato do documento](https://postext.dev/pt/docs/document-format.md#índice-remissivo)): os termos marcados com `:index[…]` e `:index{term="…"}` no texto, ordenados, agrupados pela letra inicial (pela inicial do pinyin ou pelo número de traços em chinês, pela linha do gojūon em japonês, veja `groupBy`), cada um com as páginas em que aparece. Uma entrada é o seu termo, um separador e os seus números de página; as subentradas vêm em seguida, com um passo de recuo por nível, e as linhas quebradas recuam por `turnoverIndent` para nunca se alinharem com uma subentrada.

```ts
const config: PostextConfig = {
  headingStyles: [
    // O índice em duas colunas, sob o seu próprio título.
    { id: 'index', numbered: false, layout: { layoutType: 'double', gutterWidth: { value: 6, unit: 'mm' } } },
  ],
  index: {
    fontSize: { value: 8.5, unit: 'pt' },
    lineHeight: { value: 11, unit: 'pt' },
    rangeFormat: 'chicago',
    groups: { fontFamily: 'Source Sans 3', fontWeight: 700, color: { hex: '#8a1c1c', model: 'hex' } },
  },
};
```

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `color` | — | o texto do corpo | Tipografia das entradas. Toda linha do índice, cabeças de letra inclusive, é composta em `lineHeight`; o índice mantém o seu próprio ritmo e não se encaixa na grade de linhas de base. |
| `indent` | `Dimension` | `1em` | Recuo de cada nível de subentrada. |
| `turnoverIndent` | `Dimension` | `2em` | Recuo extra das linhas quebradas de uma entrada, além do recuo do seu nível. |
| `entrySpacing` | `Dimension` | `0` | Espaço acima de cada entrada principal. |
| `separator`, `locatorSeparator`, `rangeSeparator` | `string` | `', '`, `', '`, `'–'`; os dois primeiros `'، '` em escrita árabe | O que é impresso entre o termo e a sua primeira página, entre duas páginas e entre as pontas de um intervalo. |
| `mergeRanges` | `boolean` | `true` | Junta páginas consecutivas de um mesmo formato de numeração num intervalo: `12, 13, 14` imprime `12–14`. As páginas principais nunca são juntadas. |
| `rangeFormat` | `'full' \| 'chicago'` | `'full'` | Como se escreve o segundo número de um intervalo: por extenso (`234–237`) ou sem os algarismos que tem em comum com o primeiro, como pede o *The Chicago Manual of Style* (9.64): `71–72`, `100–104`, `101–8`, `321–28`, `1496–500`. Os rótulos em algarismos romanos são sempre escritos por extenso. |
| `main` | `{ bold?, italic? }` | negrito | Como é composta uma página principal (`main` na marcação). |
| `see` | `{ label?, alsoLabel?, italic? }` | conforme o idioma, itálico (redondo em escrita árabe) | As palavras antes de uma referência cruzada. Sem valor, seguem o idioma do documento: *See* / *See also*, *Véase* / *Véase también*, *Voir* / *Voir aussi*, 见 / 另见 (見 / 另見 em chinês tradicional)… Um índice em chinês compõe a referência depois de um ponto final, sem espaço: `贾琏 12。见贾政`. |
| `locale` | `string` | o do documento | O idioma cuja ordem alfabética ordena as entradas (uma tag BCP 47, lida por `Intl.Collator`). Em espanhol, *ñ* vem depois de *n* e encabeça um grupo próprio; os acentos nunca mudam a ordem. |
| `groupBy` | `'auto' \| 'letter' \| 'pinyin' \| 'stroke' \| 'gojuon' \| 'kana' \| 'none'` | `'auto'` | O que são as cabeças de grupo. `'letter'`: a primeira letra da chave de ordenação. `'pinyin'`: uma entrada que começa com um caractere han fica sob a inicial latina da sua leitura em pinyin (贾宝玉 sob `J`), e uma chave de ordenação latina fica sob a sua letra, depois das entradas chinesas dessa letra (o collator põe as letras latinas depois dos caracteres chineses): `sort="jia mu"` fecha o `J`. `'stroke'`: sob o número de traços do primeiro caractere, `一畫`, `二畫`… (`一画`… em chinês simplificado). `'gojuon'`: uma entrada em kana fica sob a sua linha do gojūon, あ行, か行 … わ行, e `'kana'` sob o seu primeiro kana (katakana e hiragana dividem as cabeças), na ordem JIS X 4061 de um índice japonês: pela leitura (o `yomi` da marcação, senão a leitura em kana do seu rubi, senão `sort`, senão o texto), katakana como hiragana, kana pequeno como grande, ー como a vogal anterior, 清 antes de 濁 antes de 半濁; símbolos, depois números pelo valor, depois palavras latinas sob as suas letras, depois kana; uma entrada ainda encabeçada por um kanji é informada como `indexReadingMissing` e composta depois dos kana, sem cabeça. `'none'`: sem cabeças; símbolos, números e palavras ficam separados apenas por `groups.marginTop`. `'auto'` agrupa um índice japonês (`ja`, `ja-*`) pela linha do gojūon, um índice em chinês simplificado (`zh`, `zh-Hans`, `zh-CN`) por pinyin, um em chinês tradicional (`zh-Hant`, `zh-TW`, `zh-HK`) por traços, e todos os outros idiomas por letra. As entradas são ordenadas na colação de onde vêm as cabeças: um índice `zh-Hant` agrupado por pinyin é ordenado por pinyin. As leituras e os números de traços são os do collator (CLDR); onde ele lê um caractere errado (重 como *zhòng* em 重阳, 行 como *xíng* em 行业), dê à marcação uma chave `sort` em caracteres que só tenham a leitura desejada, que fica ordenada no lugar certo: `sort="崇阳"` para 重阳, `sort="航业"` para 行业. Um navegador sem dados de colação chinesa imprime um índice por pinyin ou por traços sem cabeças. |
| `ignoreArticle` | `boolean` | `true` em árabe | Ordena e agrupa as entradas árabes como se um artigo inicial `ال` (`ٱل`) não estivesse ali: البصرة fica sob ب, entre بدر e بغداد, e é impresso como foi escrito. `الله` mantém o seu artigo, e uma entrada com a sua própria chave `sort` é ordenada por essa chave tal como foi dada. Seja qual for o valor desta opção, um índice árabe ignora os sinais vocálicos e o tatweel, põe أ إ آ ٱ sob ا e ordena ؤ como و, ئ e ى como ي, ة como ه. |
| `groups.enabled` | `boolean` | `true` | Imprime uma cabeça acima de cada grupo de entradas (`A`, `B`…, ou o número de traços, `0–9` para números, `Symbols` para o resto; `数字` / `數字` e `符号` / `符號` em chinês). |
| `groups.fontFamily`, `fontSize`, `fontWeight`, `italic`, `color` | — | as das entradas, peso `700` | A fonte da cabeça de letra. Ela é composta no passo de linha das entradas. |
| `groups.marginTop` | `Dimension` | uma linha do índice | Espaço acima de cada grupo, com ou sem cabeça; nenhum acima do primeiro grupo, cuja distância do título é a do título, e nenhum no topo de uma coluna. |
| `groups.symbolsLabel`, `numbersLabel` | `string` | conforme o idioma; `'0–9'`, `'数字'` / `'數字'` em chinês | As cabeças das entradas que começam com um símbolo e com um algarismo. |

Os números de página vêm da estrutura do livro, como os do sumário: `computeOutline()` e `contentOutline()` listam as marcações de índice de um texto como entradas do tipo `'indexMark'` (com `indexMark.path`, `sort`, `see`, `seeAlso`, `main`, `range` e `index`), e `outlineFromDoc()` dá a cada uma a página em que caiu, que a construção registra em `doc.indexMarks` (`{ sourceStart, pageIndex }` por marcação). `buildDocument()` diagrama de novo um documento que imprime o seu próprio índice até os números se estabilizarem; um host que diagrama um livro capítulo a capítulo entrega ao capítulo que contém `:::index` a estrutura do livro inteiro como `PostextContent.outline`. `tocOutline()` e `indexOutline()` dividem uma estrutura no que o sumário e o índice leem, para que um host possa associar cada capítulo ao que ele imprime: o Sandbox diagrama de novo o capítulo do índice só quando uma marcação se move, e o do sumário só quando um título se move. `contentOutline()` também diz se um texto imprime um índice (`hasIndex`).