# Table of contents

> Маркер для оглавления, опережающий рендереры, которые его построят.

Source: https://docxcelerate.com/ru/docs/nodes/table-of-contents/

The kind is part of the document schema and both renderers accept it. What is missing is downstream rather than in the authoring: the element places the marker and carries its title, and building the entries from the surrounding section titles is a renderer's job.

> **Что рендереры делают сегодня:** Both shipped renderers print the title and nothing else. Building the entries from the surrounding section titles is the intent, not yet implemented.

- **Хелперы:** `TableOfContents`
- **Вид узла:** `tableOfContents`
- **Категория:** Структура
- **Разрешается:** By the renderer
- **Дочерние узлы:** None. The entries would come from the sections beside it.

| Опция | Тип | Что делает |
| --- | --- | --- |
| `id` | `string` | Stable address for the node. Engines target it and build artifacts diff on it, so treat a rename as a breaking change. Optional: a node without one takes an id from where it sits, which is what keeps branches and loops from forcing you to invent names. Two nodes claiming one id is an error rather than a race. |
| `title` | `string` | Heading for the list. Renderers fall back to their own wording. |
| `derivers` | `DeriverInvocation[]` | Values the engine computes before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`. These survive publishing and run per document — use them for anything computed from request data. `useDeriver` runs one during the build instead. |

## Как его написать

```tsx
import { TableOfContents } from "docxcelerate/template";

export const Contents: TableOfContents = () => (
  <TableOfContents id="contents" title="What is in this document" />
);
```

Он компонуется как любой другой узел и одинаково разрешается в сборках
предпросмотра, сборках движка и тестах. Помещённый прямо в шаблон, он вообще не
требует собственного компонента — `<TableOfContents id="contents" title="…" />`
и есть всё целиком.

## Недостающее — ниже по течению

Элемент ставит маркер и несёт свой заголовок. Собрать записи из заголовков
окружающих разделов — работа рендерера, и ни предпросмотр в браузере, ни
упаковщик DOCX этого пока не делают: оба печатают заголовок и на этом
останавливаются.

## Зачем размещать его уже сейчас

Это одна строка, и он начнёт печатать пункты в тот день, когда рендереры научатся
их строить. Альтернатива — список заголовков разделов, поддерживаемый вручную
внутри абзаца — станет неверной за пару релизов.

Если не хочется выпускать узел, печатающий один только заголовок, не включайте
его. Добавить позже будет так же дёшево.

## Варианты

### A titled marker

The element, and the title it carries into the document.

Source: `src/nodes/table-of-contents/basic.node.tsx`

```tsx
import { TableOfContents } from "docxcelerate/template";

/**
 * A heading standing in for the contents of the document around it.
 *
 * The shipped renderers print the title and stop — the entries themselves are
 * a renderer's job, and neither the browser preview nor the DOCX packer builds
 * them yet.
 */
export const Contents: TableOfContents = () => (
  <TableOfContents id="contents" title="What is in this letter" />
);
```

**Во что это разрешается**

```json
{
  "id": "contents",
  "kind": "tableOfContents",
  "title": "What is in this letter"
}
```

## Примечания

- `title` необязателен; рендереры используют собственную формулировку.
- Узел не содержит потомков и ничего не читает во время сборки.