# The node model

> What every node has in common, what makes them differ, and where each one is documented.

Source: https://docxcelerate.com/docs/nodes/overview/

A document is a tree of nodes. Every node comes down to three things: an **id**,
a **kind**, and a rule for producing its content.

```tsx
<Paragraph          // the kind
  id="greeting"     // the address
>
  Dear {state.name},  {/* the rule */}
</Paragraph>
```

Resolved against your data, it becomes plain JSON:

```json
{ "id": "greeting", "kind": "paragraph", "mode": "static", "text": "Dear Adaeze Nkemelu," }
```

No styling, no layout. Those get applied later, by whichever renderer you hand
the document to.

## The catalog

Each type has a page of its own, with every option it takes and a preview of
each way it can be written.

### Structure

- **[Section](https://docxcelerate.com/docs/nodes/section/)** (`section`) — Groups nodes under a titled heading.
- **[Table of contents](https://docxcelerate.com/docs/nodes/table-of-contents/)** (`tableOfContents`) — A marker for a contents list, ahead of the renderers that build one.

### Text

- **[Paragraph](https://docxcelerate.com/docs/nodes/paragraph/)** (`paragraph`) — A block of prose, written from your data or generated from prompts.

### Media

- **[Image](https://docxcelerate.com/docs/nodes/image/)** (`image`) — A picture resolved from your data or described by a prompt.
- **[Shape](https://docxcelerate.com/docs/nodes/shape/)** (`shape`) — A drawn rectangle with the document's own words on top of it.
- **Clip art** (`clipArt`) _(Planned)_ — Named visual blocks — rules, marks, callouts — drawn by the renderer.

### Data

- **[Graph](https://docxcelerate.com/docs/nodes/graph/)** (`graph`) — A real Word chart, declared as data.
- **[Table](https://docxcelerate.com/docs/nodes/table/)** (`table`) — A grid of cells, with the columns declared once.

## Ids are addresses

A node's id is how a generation endpoint targets that particular paragraph, and
how two build artifacts line up when you diff them. Rename one and you break
whatever points at it from outside — much like renaming an API route.

Keep them unique across the document. It costs you nothing and makes logs
readable.

## Where content comes from

Every node either holds its content or carries prompts for producing it. You
don't declare which — the component decides by what it supplies.

Give a paragraph text (or an `Image` a `src`, or a `Graph` its `data`) and it
resolves on your machine. Give it prompts and a placeholder instead, and it gets
filled in at request time.

Both land as the same `kind`, and differ by `mode` in the built document. `mode`
is output rather than input: the build works it out from what you supplied, then
uses it to tell an engine which nodes it still has to resolve.

Supplying both text and prompts on one element is an error, not a coin toss.

[Writing nodes](/docs/writing-nodes/) covers the prompt slots and what previews
show in their place.

## Nesting

[`Section`](/docs/nodes/section/) groups other nodes under a heading, and it
accepts any kind — including other sections.

[`Table`](/docs/nodes/table/) holds nodes too: rows, and cells with nodes inside
them. Both work on the same principle. A container holds the components you
already write, rather than introducing a second content model beside them.

## About these previews

Every preview on these pages is a real build.

`src/nodes/` in this site's repository holds one file per variant, written
against the published package. A build step resolves each one through
`buildDocument` and renders it with the same renderer `dxcl dev` serves. The
source you see is the file that ran, and the JSON is what came back.

So when a node type changes, these pages break loudly rather than going quietly
out of date.
