Schema

The schema defines every node and mark the editor supports. stesuraSchema() from @stesura/core/schema builds it: the core node specs, plus shared attributes (numbering, formatting, spacing, …) composed onto them by the global-attribute system.

Document Structure

doc              →  section+ footnotes endnotes?
section          →  section_header section_content section_footer
section_content  →  (block | table | page_break | toc | file)+

endnotes is created lazily, when the first endnote is inserted.

doc attributes:

Nodes

Block Nodes

Table placement

table is deliberately not in the block group. The containers that host tables admit them by name: section_content, header_footer_content, wrapper nodes that opt in ((block | table)+), and table_cell ((block | table)* block). Plain block+ containers (footnote_body, endnote_body) therefore exclude tables structurally.

A table can sit in a table cell, one level deep: a table in a nested table’s cell is not supported. A content expression can’t state depth, so the guards enforce it (see @stesura/core/guards). A cell never ends in a table, so the caret always has a paragraph after it, as in Word.

Consequences:

• insertTable in a table cell sizes the new table to that cell. It is refused inside a nested table, a note body, a code block, or a cell too narrow for the columns.
• Pasting a table into a cell nests it. A paste that would put a table three levels deep flattens that table into its cell’s blocks.
• Documents with a table too deep, or in a note body, are healed on load (prepareDocForLoad locally, createNormalizeTransaction in collab): the table is flattened into its cell’s blocks, with steps that converge across collab clients.
• DOCX import keeps a table in a table cell and flattens deeper ones (and tables inside footnotes/endnotes) with an import warning.
• Pagination breaks a nested table between its rows, never through one (see Pagination).

A custom container that should host tables must use (block | table)+. See Extending the Schema.

Section Nodes

section has no parse rule: pasting a section brings its blocks, not its page setup.

Inline Nodes

Special Nodes

Not in the block group; section_content admits them by name, so they cannot appear in table cells, note bodies or headers/footers.

Footnote / Endnote Nodes

Marks

Text Formatting

Styling

Track Changes

Utility

Global Attributes

Many node attributes come from the global-attribute system rather than the node spec. stesuraSchema applies them at construction, and its globalAttributes option changes which nodes carry each one. See Global Attributes.

Default bindings:

FORMATTED_NODES is heading, paragraph, image, toc and horizontal_rule. SPACED_NODES adds code_block, file, table and callout to those.

Spacing Roles

The spacing plugin replaces CSS margin collapse with computed top margins (the spacing store’s, never stored in the document) (see Global Attributes). It groups blocks into collapse chains: margins collapse between consecutive members of a chain. A container’s spacing role sets how it interacts with chains:

• Spaced (nodes carrying spacing: paragraphs, headings, tables, images, …): the node is one opaque chain member. Its children never collapse with the outside.
• Pass-through: the node’s children join the surrounding chain, so a paragraph after the wrapper collapses against the last paragraph inside it.
• Boundary: the node’s children form an isolated chain, as in a table cell.

A callout is spaced (it collapses with its neighbors as one block) and a boundary inside (its first child keeps its own spacing).

The role is inferred: a wrapper-shaped node (block node with block content, not an atom) is pass-through, unless it is spaced or a core flow boundary (section scaffolding, table/row/cell, note containers and bodies). A custom wrapper node therefore works with no registration.

To override the inference, declare spacingRole on the node spec (typed by StesuraNodeSpec from @stesura/core/schema):

import type { StesuraNodeSpec } from "@stesura/core/schema";
 
const sidebarSpec: StesuraNodeSpec = {
  content: "block+",
  group: "block",
  spacingRole: "boundary", // isolate children from the surrounding flow
  // ...
};

spacingRole: "passThrough" on a spaced node is ignored with a console error. See Extending the Schema for a full wrapper-node example.

Constants

import {
  NODE_NAMES,          // node type names; prefer these over string literals
} from "@stesura/core/schema";
 
import {
  DEFAULT_TEXT_STYLE,  // { fontSize: 10, fontFamily: "Arimo", color: null, ... }
  DEFAULT_LINE_HEIGHT, // 1.5
  DEFAULT_SPACING,     // { before: 0, after: 8 }
  PAGE_FORMATS,        // A4 (default), A3, A5, B5, envelopes, Legal, Letter
  HIGHLIGHT_COLORS,    // yellow, lime, aqua, fuchsia, red
  UNDERLINE_TYPES,     // CSS for each underline variant
  FONT_FAMILIES,       // available font families
} from "@stesura/core/constants";

Next Steps

• Global Attributes: how shared attributes are composed onto nodes.
• Extending the Schema: adding custom nodes and marks.
• Commands: Core: manipulating nodes and marks programmatically.