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 ((block | table)+): section_content, header_footer_content, and wrapper nodes that opt in. Plain block+ containers (table_cell, footnote_body, endnote_body) therefore exclude tables structurally: nested tables and tables in footnotes/endnotes are not supported.

Consequences:

• insertTable is refused inside a table, a note body or a code block.
• Pasting a table into a cell never nests: ProseMirror’s fitting relocates or flattens the content instead.
• Legacy documents containing nested tables are healed on load (createNormalizeTransaction): the inner table is flattened into its cell’s blocks, with steps that converge across collab clients.
• DOCX import flattens nested tables (and tables inside footnotes/endnotes) with an import warning.

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 and table to those.

Spacing Roles

The spacing plugin replaces CSS margin collapse with computed _marginTop attributes (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.

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.