Table of contents — Docxcelerate

Nodes

A schema kind with no helper yet — how to place one, and what it does today.

The kind is part of the letter schema and both renderers accept it, but no authoring helper is exported yet. Writing the component by hand works — a node component is a function returning a definition, and the helpers are conveniences over exactly that shape. No helper yet

Helpers: None — written by hand
Node kind: tableOfContents
Category: Structure
Resolves: By the renderer
Children: None. The entries would come from the sections beside it.

Option	Type	What it does
`id` required	`string`	Stable address for the node. Generation endpoints target it and build artifacts diff on it, so treat a rename as a breaking change.
`title`	`string`	Heading for the list. Renderers fall back to their own wording.
`derivers`	`DeriverInvocation[]`	Values computed before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`.

Writing one without a helper

The helpers are conveniences, not a gate. A node component is a function that takes your data and returns a definition, so any kind in the schema is reachable by writing that function:

import type { NodeComponent } from "docxcelerate";

export const Contents: NodeComponent<MemberData> = () => ({
  kind: "tableOfContents",
  id: "contents",
  title: "What is in this document",
});

It composes like any other node, and resolves in preview builds, engine builds and tests the same way.

Why place one now

It costs one line, and it starts printing entries the day the renderers build them. The alternative — a hand-maintained list of section titles in a paragraph — will be wrong within two releases.

If you would rather not ship a node that prints only a heading, leave it out. Adding it later is equally cheap.

Variants

Written by hand

src/nodes/table-of-contents/basic.node.ts

The definition shape the helpers would produce.

import type { NodeComponent } from "docxcelerate";
import type { SampleData } from "../sample-data.ts";

/**
 * No helper ships for this kind yet. A node component is only a function
 * returning a definition, so writing it out reaches the same place.
 *
 * The shipped renderers print the title and stop.
 */
export const Contents: NodeComponent<SampleData> = () => ({
  kind: "tableOfContents",
  id: "contents",
  title: "What is in this letter",
});

table of contents · written by hand Open ↗

What it resolves to

The node as it appears in the DocumentModel: the JSON a renderer is handed. No styling, no layout.

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

Notes

Expect a tableOfContents helper eventually, taking the same { id, title } it takes here. Written as above, adopting it is a one-line change.
The node holds no children and reads nothing at build time.

Edit this page on GitHub ↗