Configuration

A script’s format is a FormatConfig — the config half of the canonical model. It declares everything about a script that isn’t its content: its sections, block types, mark types, styling, editor behavior, per-syntax spelling, and metadata. It is seeded from a preset when a script is created, and is fully editable thereafter.

FormatConfig

The root object. Its wire version is 2, or 3 when the document uses media (see the version note below).

{
  "scriptpub": 2,
  "kind": "work",
  "meta": { "title": "Untitled Screenplay", "language": "en" },
  "preset": { "name": "Screenplay", "uri": "scriptpub:preset/screenplay" },
  "library": { … },
  "parts": { … },
  "sections": [ … ],
  "blocks": [ … ],
  "marks": [ … ],
  "syntax": { "html": { "newline": "br" } },
  "revisions": [ … ],
}

Field	Type	Required	Description
`scriptpub`	`number`	✓	Format wire version. This revision reads `2` and `3`, and emits the lowest version that expresses the document — `3` only when it carries a media construct.
`kind`	`"work" \| "collection" \| "library"`		What the document IS; default `"work"`. Collections and library indexes are catalog documents. See Collections / Libraries.
`meta`	`Meta`	✓	Work metadata — title-page material (below).
`preset`	`PresetRef`		Preset identity / provenance — `{ name?, uri? }`. See Format presets.
`library`	`LibraryConfig`		The library group (`kind: "library"` only): scan globs, organization, new-work defaults, display defaults, export targets. See Libraries.
`parts`	`PartsConfig`		Present exactly on a multi-file work’s index: split mode + part scan globs; the document’s body is the spine. See Multi-file works.
`sections`	`SectionDef[]`		Optional. Omitted or empty = an unsectioned document. See Sections & divisions.
`blocks`	`BlockDef[]`	✓	The block types. Definition order is normative — it is the kind-inference precedence order. See Blocks.
`marks`	`MarkDef[]`	✓	The inline mark types (definition order = inference precedence too). See Marks & links.
`syntax`	`object`		Document-wide adapter settings, keyed by syntax id. See Syntaxes.
`revisions`	`RevisionDef[]`		Optional. Named revision passes. See Translations, drafts & revisions.
—			Appearance is NOT config: every visual choice (block styles, typography, conditions, page geometry, settings) lives in the document stylesheet. Non-HTML syntaxes carry it as a `stylesheet` string key beside these fields.

scriptpub is the model-version counter, not the release number. The standard is pre-release (0.1) — see the Overview. The wire counter tracks the on-the-wire model independently: the meta, multi-syntax model is version 2 (the earlier single-file HTML model was 1), and version 3 adds the media constructs — object runs, the media attributes, and the media meta keys. Serializers emit the lowest version that expresses the document, so a media-free document stays 2 and opens in any older engine; readers of this revision accept both.

On `blocks` order being normative

The blocks array is not just a list — its order is the kind-inference precedence order. When a block is being recognized from its spelling, the block types are tried top to bottom and the first one whose match rules hold wins. Reordering blocks can therefore change how content is parsed. The default Text block is the implicit final fallback and is never part of this precedence. See Kind inference.

Meta

Title-page-level metadata — the union of what Fountain and FDX title pages carry natively. It is the one place in the format with no fixed vocabulary: custom keys are allowed and preserved verbatim, because title pages are inherently free-form. Only title is required.

Field	Type	Description
`title`*	`string`	The work’s title. Doubles as `<title>` in HTML.
`credit`	`string`	Credit line (“Written by”).
`author`	`string \| string[]`	Author name(s).
`source`	`string`	Source line (“Based on …”).
`draft`	`string`	Draft label / date (labels a draft).
`contact`	`string`	Contact block.
`copyright`	`string`	Copyright notice.
`license`	`string`	License.
`year`	`string`	Year of writing / publication.
`description`	`string`	One-line description. HTML spelling: `<meta name="description">`.
`uri`	`string`	Canonical URL — the document’s stable public identity. HTML spelling: `<link rel="canonical">`.
`cover`	`string`	Cover image path — a media reference, relative preferred (`"assets/cover.jpg"`) — the EPUB-convention `<meta name="cover">`. See Libraries.
`coverAlt`	`string`	The cover’s alt text (EPUB accessibility, generated cards). HTML spelling: `<meta name="cover-alt">`.
`narration`	`string`	The work’s narration audio — the default track that block-level narration clips slice into.
`narrator`	`string`	Narrator display name (→ EPUB `media:narrator`).
`language`	`string`	BCP-47 tag; default `"en"`. Doubles as `<html lang>`.
`translationOf`	`string`	Reference to the original this document translates.
`draftOf`	`string`	Reference to the document this is a draft of.
`notes`	`string`	Free notes.
(custom)	`unknown`	Any additional keys, preserved verbatim.

Note that meta.title is distinct from a preset’s preset.name. On a preset file, meta.title titles the sample body while preset.name names the preset itself.

PresetRef

A format’s provenance — which preset it was seeded from (or, on a preset file, the preset’s own identity).

Field	Type	Description
`name`	`string`	Display name, e.g. `"Screenplay"`.
`uri`	`string`	Stable identifier — `scriptpub:preset/<id>` (built-in), `scriptpub:curated/<slug>` (a shipped set), `scriptpub:local/<id>` (user-made, device-scoped), or any URL.

See Format presets for how provenance rides along when a script is created from a preset.

SyntaxSettings & RevisionDef

syntax holds document-wide adapter settings keyed by syntax id. Only html is pinned in this revision:

HtmlSettings = {
  newline?: "br" | "literal",  // in-block newline encoding; default "br"
}

revisions holds the named production passes — see Revisions: