# Configuração: cabeços e rodapés

> O que é impresso no alto e no pé de cada página: texto com marcadores, fios, caixas e imagens, conforme a paridade da página, e onde cada elemento fica

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

## Em poucas palavras

Esta página trata do que é impresso no alto e no pé de cada página. Um cabeço ou um rodapé pode trazer o número da página, o título do livro ou do capítulo, uma linha, uma caixa ou uma imagem pequena. As páginas da esquerda e as da direita podem mostrar coisas diferentes. Cada elemento pode ficar à esquerda, no centro ou à direita, ou na margem, ao lado do texto. O cabeço e o rodapé ficam dentro das margens, então nunca diminuem a área do texto.

## 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.

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `elements` | `HeaderFooterElement[]` | padrões embutidos quando `undefined`; `[]` desativa | Lista ordenada de elementos de texto e de fio. |

### 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.

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `kind` | `'text'` | — | Discriminador. |
| `id` | `string` | — | Id estável, único dentro do espaço. Outros elementos se ancoram nele com `anchor.to: '#id'`. O Sandbox atribui um ao criar o elemento. |
| `content` | `string` | `''` | String de modelo. Aceita os marcadores listados abaixo, além de `{attr.<key>}`: um atributo escrito na linha do H1 do capítulo atual (`# Title {author="I. Zango"}`). Um atributo ausente vira uma string vazia, sem aviso. Uma quebra de linha (ou os dois caracteres `\n`, escritos no modelo ou no valor de um atributo) sempre começa uma nova linha, qualquer que seja o `overflow`. O texto que um marcador copia do documento (um título, um campo do frontmatter) é impresso como está escrito: ali, só uma quebra de linha real, como a quebra de um título, começa uma nova linha. |
| `align` | `'left' \| 'center' \| 'right' \| 'justify' \| 'start' \| 'end'` | `'center'` | Alinhamento horizontal das linhas dentro da caixa do elemento. `'justify'` estica os espaços entre palavras de todas as linhas quebradas, exceto a última de cada parágrafo, para que a linha preencha a caixa; as linhas ao lado de uma capitular preenchem o espaço ao lado dela. Com `hyphenate`, uma palavra que não cabe no restante de uma linha justificada também é cortada em uma sílaba para preenchê-la. A última linha de um parágrafo, uma linha sem espaço para esticar e um texto que não quebra ficam alinhados à esquerda. O texto justificado é diagramado parágrafo a parágrafo, então várias linhas em branco entre parágrafos contam como uma. O canvas e o PDF colocam cada palavra onde o layout a pôs; o HTML alarga os espaços com `word-spacing`. `'start'` e `'end'` seguem a `direction` do texto: a direita e a esquerda de um texto da direita para a esquerda. `'left'` e `'right'` são os lados da própria caixa; em um design diagramado no fluxo de uma página da direita para a esquerda (uma faixa de abertura, o design de um título) o fluxo é espelhado, então eles são o início e o fim, como no texto corrido. |
| `direction` | `'ltr' \| 'rtl' \| 'auto'` | a do documento | Direção base do texto: para onde vão seus caracteres neutros, a ordem dos trechos em uma linha e o que significam os lados `'start'` e `'end'`. `'auto'` lê a primeira letra forte do texto resolvido e, sem ela, usa a [`direction`](https://postext.dev/pt/docs/configuration-language.md#direção-do-texto) do documento. Trechos em árabe e hebraico são lidos da direita para a esquerda, qualquer que seja a base. Um texto que contém uma letra árabe nunca recebe espaçamento entre letras (`letterSpacing` é ignorado para o texto inteiro) e suas palavras nunca são cortadas ao quebrar ou truncar a linha; uma palavra mais larga que a caixa transborda e é reportada como `unbreakableWordOverflow`. |
| `parity` | `'all' \| 'odd' \| 'even'` | `'all'` | Em quais páginas o elemento aparece (paridade do número da página: a página 1 é ímpar). |
| `pages` | `'all' \| 'body' \| 'opener' \| 'part' \| 'blank'` | `'all'` | Em quais *funções* de página o elemento aparece, combinado com `parity`. Depois do posicionamento, cada página é classificada como `'blank'` (página de preenchimento por paridade ou separador, ou sem conteúdo), `'part'` (uma página divisória de parte), `'opener'` (seu primeiro bloco é um título cujo nível ocupa a página ou força uma quebra de página antes dele: a primeira página de um capítulo) ou `'body'` (todas as outras). `pages: 'body'` esconde um cabeço nas aberturas de capítulo; `pages: 'opener'` mostra um fólio só nelas. |
| `fontFamily` | `string` | `'EB Garamond'` | Família tipográfica. |
| `fontSize` | `Dimension` | `8 pt` | Tamanho da fonte. |
| `fontWeight` | `number` | `400` | Peso da fonte (100–900). |
| `italic` | `boolean` | `false` | Se o texto é desenhado em itálico. |
| `color` | `ColorValue` | `#000000` | Cor do texto. |
| `overflow` | `'wrap' \| 'ellipsis-start' \| 'ellipsis-middle' \| 'ellipsis-end' \| 'clip'` | `'wrap'` em designs de título e de parte; senão, `'ellipsis-end'` | Como o motor trata o texto que excede a largura disponível do elemento. `'wrap'` quebra o texto em várias linhas; as variantes com reticências mantêm cada linha em uma só linha e a truncam com `…` no início, no meio ou no fim; `'clip'` corta rente à caixa delimitadora do elemento, sem inserir nenhum caractere. As quebras de linha do conteúdo valem em todos os modos: os modos de reticências e de corte truncam ou cortam cada linha separadamente. Um elemento que omite `overflow` segue o padrão do seu espaço: num design de título (`advancedDesign.slot`) ou numa página de parte (`parts.design`, `parts.versoDesign`) quebra linha; num cabeçalho, num fólio ou numa linha de parte do sumário (`toc.parts.design`, uma linha de altura fixa) termina em `…`. Defina `'wrap'` num cabeçalho que possa ocupar várias linhas (um endereço), ou reticências num antetítulo que deva ficar numa linha dentro de uma abertura. Uma linha cortada com reticências, ou recortada com tinta além da caixa, é avisada pelo aviso de conteúdo `designTextTruncated`, uma vez por elemento e página (um cabeçalho ou um fólio, uma vez por elemento e capítulo). Uma configuração salva antes do postext 1.24 (`configVersion` 9 ou anterior) é lida com `'ellipsis-end'` em cada texto de título ou de parte que não o define, para que as páginas não se movam. Um texto com `dropCap` quebra linhas independentemente deste valor; com `'clip'`, suas linhas ainda são cortadas na borda de uma caixa de altura fixa. `'ellipsis-end'` e `'ellipsis-start'` cortam em um limite de palavra (*The history of…*, não *The history of th…*), e nenhum espaço ou pontuação de ligação (vírgula, dois-pontos, travessão, barra, parêntese de abertura) encosta nas reticências. Uma palavra só é cortada onde for preciso quando o limite de palavra, descartada essa pontuação, manteria menos da metade do que cabe: uma única palavra longa, ou um URL (*http://exampl…*, não *http…*). Um espaço não separável ou um hífen não separável (U+2011, como em *MS‑DOS*) não é limite de palavra; `'ellipsis-middle'` corta em qualquer ponto, mas descarta os espaços ao lado das reticências. Até o postext 1.4, todos os modos cortavam no último caractere que cabia, espaços incluídos. |
| `verticalAlign` | `'top' \| 'middle' \| 'bottom'` | `'middle'` | Onde o texto fica dentro de uma caixa mais alta que suas linhas: uma `placement.size.height` fixa, ou uma caixa esticada por um vizinho ancorado. Quando as linhas são mais altas que a caixa (um numeral grande em uma caixa de altura fixa, uma `lineHeight` apertada), elas transbordam pelo lado que o alinhamento deixa livre, como faz o alinhamento flex do CSS: `'bottom'` mantém o pé da caixa da última linha no pé da caixa e transborda por cima, `'middle'` transborda por igual nas duas pontas, `'top'` pelo pé. Até o postext 1.4, essas linhas sempre pendiam do topo, qualquer que fosse o alinhamento. Uma `dropCap` acompanha suas linhas (até o postext 1.4 ela ficava no topo de uma caixa em que `'middle'` ou `'bottom'` as tinha deslocado para baixo). |
| `lineHeight` | `number \| Dimension` | `1.2` | Entrelinha das linhas do elemento. Um número é um múltiplo de `fontSize`. Uma `Dimension` também é aceita, do mesmo jeito em que se escrevem todas as outras entrelinhas da configuração: `em` / `rem` é o mesmo múltiplo, e um comprimento absoluto (`pt`, `mm`, `px`…) é a distância entre linhas de base: `{ value: 15.5, unit: 'pt' }` define uma entrelinha de 15,5 pt, qualquer que seja o tamanho. Qualquer outra coisa (zero, um número negativo, uma dimensão malformada) assume o padrão. Até o postext 1.4, uma `Dimension` aqui tornava impossível medir a altura do design: uma abertura não reservava espaço nenhum, nem mesmo a sua `minHeight`, e o corpo passava por baixo do título. |
| `letterSpacing` | `Dimension` | `0` | Tracking: espaço extra avançado depois de cada caractere, espaços incluídos, exatamente como faz o `letter-spacing` do CSS. As larguras medidas crescem com ele, então uma caixa de largura automática continua justa. Ele nunca muda os glifos: as ligaduras da fonte ficam em canvas, HTML, EPUB e PDF (até o postext 1.27, canvas e HTML as perdiam no texto de design com tracking, que saía mais largo que o medido). Um trecho em hebraico leva tracking como o texto latino; só um texto com letras árabes não leva. O tracking depois do último caractere de uma linha fica fora do alinhamento e da caixa de largura automática, de modo que um título com tracking centralizado fica centralizado nas suas letras, um alinhado à direita termina na borda e a última letra de uma linha justificada chega à borda (até o postext 1.4 eles ficavam meia unidade de tracking, ou uma inteira, à esquerda, e um elemento ancorado à direita de outro com tracking ficava uma unidade de tracking mais longe). Um valor negativo aperta as letras (um título de display a 36 pt costuma levar `{ value: -0.3, unit: 'pt' }`) e as larguras diminuem do mesmo modo; canvas, HTML e PDF o pintam igual (até o postext 1.4 um valor negativo era aplicado como `0`, sem aviso). |
| `textTransform` | `'none' \| 'uppercase'` | `'none'` | Transformação de caixa aplicada ao texto resolvido, marcadores incluídos: o título de uma parte em maiúsculas no sumário. |
| `box` | `ElementBoxStyle` | — | Fundo e borda opcionais desenhados atrás do texto: `backgroundColor`, `borderColor`, `borderWidth`, `borderRadius` e um `padding` por lado que amplia a caixa além do texto (veja [Elementos de caixa](https://postext.dev/pt/docs/configuration-headers-footers.md#elementos-de-caixa) para os campos). |
| `dropCap` | `{ lines, fontFamily, fontWeight, fontSize, color, gap }` | — | Capitular: a primeira letra composta em tamanho grande ao lado das primeiras `lines` linhas (padrão 2), com família, peso e cor próprios, a `gap` de distância do texto. A letra assenta na linha de base da última linha que ocupa, e `fontSize` tem como padrão o tamanho que alinha o topo dela com as maiúsculas da primeira linha: o tamanho do texto mais `lines` − 1 entrelinhas, considerando as maiúsculas como 0,72 do tamanho da letra (uma família cujas maiúsculas sejam bem mais altas ou mais baixas que isso pede um `fontSize` próprio). Um texto com capitular quebra linhas qualquer que seja o seu `overflow`; com `'clip'`, suas linhas ainda são cortadas na borda de uma caixa de altura fixa. Uma `color` vinculada à paleta acompanha as paletas de parte e de seção, como o resto do design. No design de um título, a letra não reserva espaço abaixo do texto: a parte da caixa da sua linha que fica abaixo da linha de base não empurra o corpo para baixo. Uma letra que desce abaixo da linha de base (um Q ou um J em muitas famílias) pode então invadir o espaço sob o design: dê ao título uma `marginBottom` para isso. Até o postext 1.4, o tamanho padrão deixava a letra tão alta quanto todas as caixas de linha que ela ocupa, de modo que o topo dela ficava acima da primeira linha; um `overflow` diferente de `'wrap'` descartava a letra sem aviso; uma paleta de seção ou de parte deixava a cor dela como estava; e uma letra tão profunda quanto o texto ao lado podia empurrar o corpo uma linha da grade para baixo. Configurações salvas antes mantêm o tamanho do 1.4, escrito como `fontSize` (veja [Pacotes escritos pelo postext 1.4 ou anterior](https://postext.dev/pt/docs/configuration-bundles.md#pacotes-gravados-pelo-postext-14-ou-anterior)). Uma capitular no texto corrido é definida pelos estilos de parágrafo e de título (veja [Capitulares](https://postext.dev/pt/docs/configuration-text.md#capitulares)), com as alturas das maiúsculas medidas nas fontes. |
| `paragraphIndent` | `Dimension` | `0` | Recuo de primeira linha de todos os parágrafos depois do primeiro. Uma quebra de linha no conteúdo (ou os dois caracteres `\n`, para texto que vem do valor de um atributo) separa parágrafos; quebras de linha consecutivas contam como uma. |
| `hyphenate` | `boolean` | `false` | Quando é `true` e o texto quebra linhas (`overflow: 'wrap'`, ou uma `dropCap`, que sempre quebra), as palavras longas que ainda transbordariam depois de uma quebra de linha normal são divididas nos limites de sílaba (usando o idioma de hifenização ativo do documento), com um hífen condicional na quebra. Em um texto justificado (`align: 'justify'`), uma palavra que não cabe no restante de uma linha também é cortada na última divisão silábica que cabe, para preencher a linha. |
| `inlineMarks` | `boolean` | `false` | Lê o texto resolvido (valores dos marcadores incluídos) como Markdown inline: `**bold**`, `*italic*`, `^superscript^`, `~subscript~`. Desativado, os sinais são impressos como foram escritos. No design de um título, `{titleText}` então mantém os trechos de negrito, itálico, sobrescrito e subscrito do próprio título (`*Pneumocystis*`, `CO~2~`), com os demais caracteres escapados para serem impressos como foram escritos (desde o postext 1.19). Veja [Marcas inline e contornos](https://postext.dev/pt/docs/configuration-headers-footers.md#marcas-inline-e-contornos). |
| `stroke` | `{ width, color?, hollow? }` | — | Contorno desenhado em volta das letras: `width` (uma `Dimension`, centrada nas bordas dos glifos), `color` (padrão: a cor do texto; uma capitular usa a própria cor) e `hollow` (`true` pinta só o contorno). Veja [Marcas inline e contornos](https://postext.dev/pt/docs/configuration-headers-footers.md#marcas-inline-e-contornos). |
| `writingMode` | `'horizontal-tb' \| 'vertical-rl'` | `'horizontal-tb'` | `'vertical-rl'` compõe o texto de cima para baixo, com as linhas da direita para a esquerda e os caracteres em pé: um cabeço descendo pela margem externa, um título vertical ao lado de um capítulo horizontal. Veja [Elementos de texto verticais](https://postext.dev/pt/docs/configuration-headers-footers.md#elementos-de-texto-verticais). |
| `reserve` | `boolean` | `true` | Só em designs de título: se o elemento conta para a altura que o título reserva no fluxo do texto. `false` para decoração que pode ficar sob o texto (um selo no pé da página, uma moldura, uma faixa lateral). Veja [Altura reservada](https://postext.dev/pt/docs/configuration-headings.md#altura-reservada). Os designs de cabeçalho, de rodapé e de parte o ignoram. |
| `marginFromBody` | `Dimension` | `6 pt` | Distância absoluta entre a borda do elemento voltada para o corpo e a borda do corpo. Independe dos outros elementos. Migrado para `placement.offset.y`. |
| `marginFromEdge` | `Dimension` | `0 pt` | Recuo horizontal a partir da borda de conteúdo alinhada. Só se aplica quando `align` é `'left'` ou `'right'`. Migrado para `placement.offset.x`. |
| `placement` | `ElementPlacement` | derivado de `align` + `marginFromBody` + `marginFromEdge` | Posicionamento avançado (veja abaixo). Quando definido, tem precedência sobre os campos planos antigos. |

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](https://postext.dev/pt/docs/configuration-headers-footers.md#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](https://postext.dev/pt/docs/configuration-styles.md#estilos-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](https://postext.dev/pt/docs/configuration-headers-footers.md#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](https://postext.dev/pt/docs/configuration-headers-footers.md#palavras-guia-primeira-e-última-marca) 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.

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

```md
:::paragraphs{style="entry"}
**Aback.** Said of the sails when pressed back against the mast.

**Abaft.** Towards the stern, or behind a given point.
:::
```

```ts
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](https://postext.dev/pt/docs/configuration-headings.md#a-quem-pertencem-as-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.

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

```json
{ "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" } } } }
```

```md
# 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).

```json
{ "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` depende do espaço.** Num design de título ou numa página de parte, um título longo quebra em mais linhas; num cabeçalho, num fólio ou numa linha de parte do sumário, um texto largo demais para o espaço é cortado em uma linha com `…`. Defina `overflow: 'wrap'` num cabeçalho que possa ficar longo (um endereço, uma linha de autoria) e confira os avisos `designTextTruncated` dos textos cortados. 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](https://postext.dev/pt/docs/configuration-headings.md#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](https://www.w3.org/TR/clreq/#x7-2-page-headers-footers-etc); [JLREQ §2.6](https://www.w3.org/TR/jlreq/#running_heads_and_page_numbers) para o japonês):

| Convenção | Onde | Como configurar |
| --- | --- | --- |
| Cabeçalho e rodapé horizontais | Acima e abaixo da mancha, como nos livros horizontais; o mais comum. | O cabeçalho e o rodapé como estão. |
| Margem externa (estilo 中缝, 邊峰 em Taiwan) | Descendo pela margem externa: o título do capítulo ou do livro a partir de uns quatro caracteres abaixo do topo da mancha, o fólio terminando uns cinco acima do pé dela, em numerais chineses, a cerca de 80 % do tamanho do corpo. | Dois elementos verticais ancorados em `'outer'`, abaixo. |
| Canto externo do pé | O fólio no pé da página, no canto externo (as regras de Taiwan para livros 中式). | Um elemento horizontal no rodapé em `'bottom-left'` com `parity: 'odd'` e outro em `'bottom-right'` com `parity: 'even'`, em um livro com encadernação à direita (o contrário em um com encadernação à esquerda). |

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):

```json
{
  "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](https://postext.dev/pt/docs/configuration-headers-footers.md#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.

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `kind` | `'rule'` | — | Discriminador. |
| `id` | `string` | — | Id estável, único dentro do espaço, para referências `anchor.to: '#id'`. |
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Um fio horizontal se estende por `placement.size.width` (`'fill'` = até a borda do contêiner) e tem `thickness` de altura. Um fio vertical desce por `placement.size.height` (`'fill'` ou não definido = até a borda do contêiner) e tem `thickness` de largura: um divisor entre um cabeço e um fólio. |
| `color` | `ColorValue` | `#000000` | Cor do traço. |
| `thickness` | `Dimension` | `0.5 pt` | Espessura da linha. Um fio que a omite é desenhado com o padrão (até o postext 1.4 não pintava nada). |
| `width` | `Dimension \| 'full'` | `'full'` | `'full'` ocupa a área de conteúdo; uma Dimension limita a linha a um comprimento fixo, posicionado por `align`. |
| `align` | `'left' \| 'center' \| 'right'` | `'center'` | Alinhamento quando `width` não é `'full'`. |
| `marginFromBody` | `Dimension` | `6 pt` | Distância absoluta entre a borda do fio voltada para o corpo e a borda do corpo. Independe dos outros elementos. |
| `marginFromEdge` | `Dimension` | `0 pt` | Recuo horizontal a partir da borda de conteúdo alinhada. Só se aplica quando `width` é uma `Dimension` fixa e `align` é `'left'` ou `'right'`. |
| `parity` | `'all' \| 'odd' \| 'even'` | `'all'` | Em quais páginas o fio aparece. |
| `pages` | `'all' \| 'body' \| 'opener' \| 'part' \| 'blank'` | `'all'` | Funções de página em que o fio aparece (veja o campo `pages` dos elementos de texto). |
| `reserve` | `boolean` | `true` | Só em designs de título: se o fio conta para a altura que o título reserva no fluxo do texto (veja [Altura reservada](https://postext.dev/pt/docs/configuration-headings.md#altura-reservada)). |
| `placement` | `ElementPlacement` | derivado de `align` + `marginFromBody` + `marginFromEdge` | Posicionamento avançado (veja [Posicionamento de elementos](https://postext.dev/pt/docs/configuration-headers-footers.md#posicionamento-de-elementos)). `size.width` / `size.height` definem o comprimento do fio; `width: 'fill'` é o antigo `'full'`. |

### 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”.

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `kind` | `'box'` | — | Discriminador. |
| `id` | `string` | — | Id estável, único dentro do espaço. Os elementos irmãos se ancoram nele com `anchor.to: '#id'`. O Sandbox atribui um ao criar o elemento. |
| `style.backgroundColor` | `ColorValue` | `transparent` | Cor de preenchimento. Defina como `transparent` para uma caixa só com contorno. |
| `style.borderColor` | `ColorValue` | `transparent` | Cor do traço. |
| `style.borderWidth` | `Dimension` | `0 pt` | Espessura do traço. Os traços são pintados no lado de dentro do retângulo delimitador da caixa, para que as dimensões externas não mudem: a borda externa do traço acompanha a borda da caixa, e uma caixa arredondada mantém o raio externo. Um traço tão largo quanto a caixa a preenche. Canvas, HTML e PDF o desenham igual (até o postext 1.4, o canvas e o PDF centravam o traço na borda, com metade dele fora da caixa). |
| `style.borderRadius` | `Dimension` | `0 pt` | Raio dos cantos. Limitado à metade do lado menor no momento da renderização. |
| `placement` | `ElementPlacement` | — | Obrigatório. Veja “Posicionamento de elementos” abaixo. |
| `parity` | `'all' \| 'odd' \| 'even'` | `'all'` | Em quais páginas a caixa aparece. |
| `pages` | `'all' \| 'body' \| 'opener' \| 'part' \| 'blank'` | `'all'` | Funções de página em que a caixa aparece (veja o campo `pages` dos elementos de texto). |
| `reserve` | `boolean` | `true` | Só em designs de título: se a caixa conta para a altura que o título reserva no fluxo do texto (veja [Altura reservada](https://postext.dev/pt/docs/configuration-headings.md#altura-reservada)). |

### 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.

```ts
{
  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.

| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | — | Identificador estável; outros elementos podem se ancorar nele como `#id`. |
| `resourceId` | `string` | — | Id de um `Resource` bitmap ou SVG do documento. Pode conter marcadores, entre eles `{attr.<key>}`, preenchidos por título, parte ou página. |
| `decorative` | `boolean` | `false` | A imagem é só decoração (um ornamento, uma faixa): não passa texto alternativo para a saída, mesmo quando o recurso tem um (veja abaixo). |
| `placement` | `ElementPlacement` | — | Âncora, deslocamento e tamanho (veja [Posicionamento de elementos](https://postext.dev/pt/docs/configuration-headers-footers.md#posicionamento-de-elementos)). Um lado `'fill'` vai até a borda do contêiner. |
| `parity`, `pages` | como acima | `'all'` | Em quais páginas a imagem aparece. |
| `reserve` | `boolean` | `true` | Só em designs de título: se a imagem conta para a altura que o título reserva no fluxo do texto (veja [Altura reservada](https://postext.dev/pt/docs/configuration-headings.md#altura-reservada)). |

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:

```ts
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:

```json
{ "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](https://postext.dev/pt/docs/configuration-page-layout.md#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](https://postext.dev/pt/docs/configuration-headers-footers.md#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](https://postext.dev/pt/docs/configuration-headings.md#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.