Self-organising documents

Model a document's structure as data, once, then render every view from it — contents, summary, index. Reorder one record and every view follows.

The pattern

One collection, a row definition, and two views:

#chapters: [
  { number: I, title: The Lamp, pages: 14 }
  { number: II, title: The Watch, pages: 22 }
  { number: III, title: The Relief, pages: 9 }
] !!

#tocrow(number, title, pages)
(li ::number::. ::title:: — ::pages:: pp. li)
tocrow#

(h2 Contents h2)

A table of contents of the headings is built in: @@@code @contents code@@@ (see
(a(href: /docs/write/academic/) Papers & theses a)). The pattern below makes any
other list — chapters with page counts, figures, a glossary.

@ul
(each @chapters as ch)
@tocrow(@ch.number, @ch.title, @ch.pages)
(end)
ul@

In this book: (each @chapters as ch)@ch.title(if @ch.last).(else), (end)(end)

<h2>Contents</h2>
<ul><li>I. The Lamp — 14 pp.</li><li>II. The Watch — 22 pp.</li><li>III. The Relief — 9 pp.</li></ul>
<p>In this book: The Lamp, The Watch, The Relief.</p>

Inside the loop, @ch.title reads a field; passed to @tocrow, it arrives as ::title:: in the definition.

What it stands on

• Data as the source of truth — Data.
• Loops and positions — Iteration.
• A row definition fed by data — Defining nodes.
• Lists that grow across files, one entry per chapter — Additive partials.

What needs a script

Arithmetic and cross-references — "Figure 3", running page totals, "as shown above" — are not core features. Store the numbers in the data, or compute them with a <% %> script (see Derived content). Loop positions count from 0, so for 1-based numbers use @ol.

Common mistakes

• Writing ::ch.title:: in a loop — placeholders live only in definitions; use @ch.title.
• Hand-writing the contents next to the chapters — it drifts; loop the data instead.

See also

Iteration · Data · Additive partials · Multi-file documents · Derived content