SPEC-199
ID:SPEC-199Status:draft

Marquise: the content model as its own project

claude/adr-049-framework-components View source
Related 21
History 31
  1. 77e1d42
    Content editedby bjornolofandersson
  2. ac6a814
    Content editedby bjornolofandersson
  3. 565596c
    Content editedby bjornolofandersson
  4. 9a24869
    Content editedby bjornolofandersson
  5. 83861be
    Content editedby bjornolofandersson
  6. 0ea77a0
    Content editedby bjornolofandersson
  7. 9072a8a
    Content editedby bjornolofandersson
  8. 499f397
    Content editedby bjornolofandersson
  9. 7f1441e
    Content editedby bjornolofandersson
  10. a5287c7
    Content editedby bjornolofandersson
  11. e7f6b74
    Content editedby bjornolofandersson
  12. 09202a6
    Content editedby bjornolofandersson
  13. 919ae20
    Content editedby bjornolofandersson
  14. 69e646f
    Content editedby bjornolofandersson
  15. da9fe83
    Content editedby bjornolofandersson
  16. 747f7c2
    Content editedby bjornolofandersson
  17. c1a703d
    Content editedby bjornolofandersson
  18. 2f2187f
    Content editedby bjornolofandersson
  19. 0996b24
    Content editedby bjornolofandersson
  20. d369288
    Content editedby bjornolofandersson
  21. b14f3b5
    Content editedby bjornolofandersson
  22. bb9cb05
    Content editedby bjornolofandersson
  23. ad006c0
    Content editedby bjornolofandersson
  24. 584e077
    Content editedby bjornolofandersson
  25. 8607cc6
    Content editedby bjornolofandersson
  26. c36b759
    Content editedby bjornolofandersson
  27. 2d5d853
    Content editedby bjornolofandersson
  28. a7ffbc3
    Content editedby bjornolofandersson
  29. a704f22
    Content editedby bjornolofandersson
  30. 30bc19f
    Content editedby bjornolofandersson
  31. c27a837
    Created (draft)by bjornolofandersson

Summary

Refrakt's most general idea is not its themes or its rune library. It is that an author writes ordinary Markdown inside a tag, and a declared content model reads typed values out of it: a heading becomes headline, a list becomes items. Nothing else on the market does this for the body of a document. Markdoc validates a tag's attributes but treats its children as untyped content; MDX gives components but makes authors write props as JSX; content-collection tools type the frontmatter, not the body.

Marquise is that idea on its own, built on Markdoc:

  • a definition file declares a tag's attributes, content model and computed values;
  • authors get validation, editor support and a grammar an AI can write against;
  • developers get typed props and draw the tag with their own React, Vue, Svelte or Astro component;
  • examples live in the definition and are tested against it.

Refrakt becomes Marquise's largest user: Marquise, plus its design vocabulary, the engine and themes, the rune library, and the site pipeline.

Marquise works on one document at a time. It types the content inside a document and knows nothing of sites: routes, URLs, navigation, or how pages refer to each other. That is the job of a site layer, whether the framework's own (Astro content collections, Next, Nuxt Content) or refrakt, which adds the whole site. Marquise cooperates with a site layer through hooks (host values, deferred definitions) and never contains one.

This spec is the breakdown: what goes, what stays, what has to be split first, the decisions to make, and an order that keeps every step useful to refrakt even if the break-out never happens. The name comes from the marquise gem cut, which also starts like Markdoc.

Who it is for

Tagline: "Markdown in, typed props out." The line under it: "Your Markdown already has structure. Marquise reads it."

Every alternative makes a team choose between content that reads as prose and content that is structured. Marquise gives both: authors write plain Markdown, developers receive typed data.

Primary audience: framework teams whose content is written by someone else. A React, Vue, Svelte or Astro site with its own design system, whose pages are built from content blocks (hero, pricing, FAQ, recipe, product), written by marketers, writers or an AI. The authors never touch JSX; the developers' own components receive validated, typed values.

Secondary audiences:

  • Teams generating content with AI. A model writes Markdown far more reliably than JSX or nested JSON. Marquise gives it a grammar and examples, then validates what it wrote with error ids it can act on: write, validate, fix.
  • Docs and design-system teams: component docs and API sections, with examples tested against their definitions.
  • Teams keeping content in git rather than a headless CMS, who still want structure and schema.org output.

Not for: a whole site with themes and no frontend work (refrakt); relational data such as inventories (a database or CMS); unstructured blogs (plain Markdown).

Beyond rendering: Markdown as a data store (explored 2026-11-15, notes/marquise-foundation.md section 18). A resolved shape node is plain data before any renderer sees it, so rendering is one consumer of three: render, extract (typed records as JSON, an API, a search index, a feed) and write (changing records by address, keeping the Markdown intact). Extract plus write makes Markdown a data store: readable files, reviewable diffs, git history, no service, and a schema guaranteeing the data's shape. Refrakt's plan files already work this way. Use cases include structured records people write as prose (recipes, events, changelogs, decision records), content as an API from git, search indexes with real fields, AI agents maintaining structured project knowledge, and data-quality gates in CI. The line: extraction per document and the write path in core; cross-document queries in the corpus layer; no database features, git being the storage. Tagline candidate covering both: "Markdown in, typed data out."

AlternativeWhat it givesWhat Marquise adds
MDXcomponents inside Markdownauthors never write JSX; content stays prose; the body is validated; content cannot run code, which matters when non-developers or an AI write it
Markdoc alonetags with validated attributestyped bodies (content models), definitions in .md, generated types, tested examples, editor tooling
Content collections (Astro, Velite, Contentlayer)typed frontmattertyped body content; complementary, since Marquise works on one document and they handle the site
Headless CMSstructure, an editing UIplain files in git, readable diffs, no service to run

Marquise or refrakt. Choose Marquise when you already have a site (framework, routing, design system, components) and want typed content in it with nothing else imposed. Choose refrakt when you want the site: themes, a design language, a rune library, navigation, cross-page features. They are a ladder, not a fork: the same definitions and content work in both, so a team can start with Marquise and add refrakt's runes, templates or themes later without rewriting content, and a refrakt site can use Marquise components for app-specific parts (ADR-049).

The audience mostly uses MDX, not Markdoc, so the story is "move from MDX and keep your components". The first page shows it rather than describing it: Markdown on one side, typed props on the other.

Marquise is the stable product; refrakt is the lab

Recorded 2026-11-12. Refrakt has grown in many directions at once (themes, a design language, a large rune library, plan tooling, site features, editor), which is why a 1.0 has been hard to reach. Marquise is not only a smaller package: it is where stability lives.

  • Refrakt stays the lab. New ideas are tried there first, on real content, and may stay 0.x for as long as that is useful.
  • Marquise ships 1.0 from what is already built and settled, not from what is planned. It does not wait for refrakt's specs to settle; it freezes a small core that already has.
  • Ideas graduate one way. A feature moves into Marquise only when its spec is implemented in refrakt, has been used on real content, and can arrive as an additive change. Marquise has no experimental flags: what is in it is stable.
  • Semver from 1.0. A breaking change waits for a major release and comes with a codemod. Marquise versions independently; refrakt pins a range and adapts to Marquise, never the reverse.
  • Every hook is public API. 1.0 ships only the hooks refrakt needs at that point. The rest arrive with the features that need them.
  • Saying no is the point. A request that needs a site, a theme or a design vocabulary belongs in refrakt, or in the user's own site layer.

What 1.0 contains

Revised 2026-11-19 (notes/marquise-foundation.md, X1); updated 2026-11-21 from Marquise's scope.md after the third review: 1.0 is the read path, records included, with the content-model revision built in refrakt first, so 1.0 ships the revised format.

In 1.0Status today
Indentation-tolerant parsing; one syntax, MarkdocSPEC-170, shipped
Shape files: frontmatter attributes, content, description, summary, plainSPEC-145, accepted; five definitions live
{% example %} blocks in a definition's body, file#id addressing, examples in tooling (notes Y5)SPEC-197, draft: built and used during 0.x, replacing refrakt's fixtures
Document shapes, minimal (notes Y4): a shape applied to a whole document; frontmatter as its attributes, undeclared keys passed to the host, shape, id and lang reservedto be built and used during 0.x, through plan's rebuild
The revised content model (notes, section 17): groups and position: last, as: block | inline | text and value types, item models with task lists and inline matchers, sections found by heading (nested) with heading templates, lists of references (items: { as: ref }), counts, tag: matches for explicit child shapes; matching and analysis per SPEC-201 D1–D8to be built in refrakt first, compiling down to the existing resolver; SPEC-200, draft
Paragraph and item templates (template:, SPEC-201 D8), if proven during 0.xto be built and used during 0.x; additive otherwise
Rules a shape declares, with @marquise-md/selectors (the grammar and its public vocabulary API), if proven (notes Y17, Q3, Q4)to be built and used during 0.x through plan's rebuild; additive otherwise
marquise explain and inlay hints (notes Y16)to be built with the content-model revision
marquise check, marquise schema, the published finding cataloguepartly built (refrakt validate, refrakt contracts)
Attribute and content validation, with finding ids and addressesin use (refrakt validate); addresses new (notes, section 19)
Records (extraction), JSON Schema, the Standard Schema validator, generated typestypes exist; records and the validator new and small
The preprocess hook, with provenance and declared dependenciesSPEC-141, shipped (the hook); include itself is a satellite (below)
The shape node, the generic renderers, componentsADR-049, proposed: the one new piece, and the product itself
The plain presentationnew, small
validate, types, extract, format, reference, the language server; the template engine in the public APIexist except extract, to be split from refrakt
@marquise-md/schema and @marquise-md/include, first-party satellitesSPEC-130, SPEC-141, shipped

A definition's body holds only examples in 1.0 (revised 2026-11-19, notes Y5; earlier it had to be empty): {% example %} blocks, per SPEC-197 D2, built during 0.x by moving refrakt's fixtures into its definitions (SPEC-197 D6). Other body blocks stay additive; write templates are not among them, since compact forms are template: in frontmatter (notes Q8).

After 1.0, each as a minor release once it graduates

Until it graduates, a feature here lives in its own 0.x package beside Marquise 1.0 (@marquise-md/write, @marquise-md/deferred), so core stays stable with no experimental flags (notes Q5/S6, 2026-11-21). Heavy, optional ones (the write path, the CEL evaluator) stay separate packages after graduating, installed into an instance (createMarquise({ writer, computes }); notes Q10).

FeatureWaits for
The write path: addresses for edits, edit operations, writing forms, the two writers (notes Q8)the parser spike (notes X5); Rivière's plan rebuild as its first real user
Compact forms owned by child shapes (a bare shape name matching every form), declared as templates, with write templatesbeing built in refrakt, which keeps emitTag in its own extension namespace meanwhile (notes Y2)
computes in CEL (notes, "Computes in CEL"; SPEC-195 D1 and D8 reopened), prepare, the value vocabulary, selects()a spike on CEL's JavaScript implementations; SPEC-194, SPEC-195's vocabulary implemented in refrakt
source()SPEC-198
Deferred shapes (definitions); dimensions on documents, fills, folder defaultsrefrakt's pipeline and Rivière using them
Kits, dimensions, presets, bindings, middlewarea design language built on them, refrakt's first
MigrationsSPEC-189
MCPthe table of operations (notes A4)
Comark accepted as an input syntax (parsed, validated, rendered; no tooling of its own)users asking for it (notes Y8: Markdoc is the syntax)
@marquise-md/composeSPEC-168, SPEC-177 accepted and implemented

Prerequisites

NeedsFromState on 2026-11-12
Every rune is input and templateADR-048, SPEC-194accepted
One value vocabularySPEC-195accepted
Components replace templates; the rune nodeADR-049proposed
Definition bodies, examples, file#idSPEC-197draft
source() and output()SPEC-198draft

Note 2026-11-21: where this spec's details differ from Marquise's concept docs (the worked example's imports, finding names, slot syntax), the concept docs are current.

The boundary

A piece goes to Marquise if it needs only definitions and content. It stays with refrakt if it needs themes, the engine, the design vocabulary or a site.

Dependencies run one way: refrakt depends on Marquise, never the reverse. Refrakt plugs in through general hooks that any other host could use too:

HookRefrakt uses it for
Shared attributes: attributes every definition accepts, with a rule for whichthe universal attributes (width, tint, reveal…), gated by declared structure
A wrapper around a rune and around a slot in the renderersthe engine root, background layers, the dimensions prop, part attributes (ADR-049 decision 8)
Presentations: something other than a component that draws a definitionthe identity transform and themes; templates, until @marquise-md/compose exists
Template tags and placeable definitions a host adds to the template language, once @marquise-md/compose existsrefrakt's primitives (section, attribution, frame, codeblock), group with its layouts, metablock, and SPEC-177's theme and site template lookup
Deferred definitions: a definition left as a placeholder holding its source, expanded later when the host supplies valuesrunes whose data reads the entity registry, expanded after the cross-page pipeline (SPEC-194 D12.4); today's capture and re-parse in deferred-body.ts
prepare stages registered by packagesnative runes' computations (SPEC-194 D3)
File roots contributed by packagescore:, marketing: for include and snippet (SPEC-197 D4)
Extension namespaces in definitions: each extension owns one key, its name, at the levels it declares (shape, attribute, field, item model), with a schema Marquise validatesrefrakt: holding role, placedBy, metaFields, registers, blocks, defaults (moved by codemod); schema: belongs to @marquise-md/schema, riviere: to Rivière
Preprocess tags registered by packagesdata, snippet: tags that resolve to content before the transform, as the include satellite does
Host values: named values a host supplies to every expression$page and $site (SPEC-194 D12), which refrakt fills from its loader; Marquise defines no site model
Error presentation: how a failure that must stay visible on the page is drawnrefrakt's {% hint type="caution" %} callout (data-emit.ts:104 today). By default a failure is only a recorded finding

Extension namespaces. Decided 2026-11-18 (notes/marquise-foundation.md, section 11, "Extensions in shape files"). An extension owns exactly one key in a definition, its name, at every level where it registers one, and puts everything it needs inside. Two packages claiming one name is a loading error. An unknown key in core or inside a known namespace is an error finding; a key that is neither core nor a registered namespace is an info finding ("not installed") and passed through untouched, so a shape library carrying hints for an extension still loads without it, while typos are still caught. Marquise validates each namespace against the schema its extension registers, composes those schemas into the shape-file schema the language server uses, never interprets the data (extensions read shape.extensions.<name>), and publishes it as vendor keywords (x-<name>). A key graduates into core by migration when more than one consumer needs it; the summary projection (summary: [title, status]) is core from the start. Authors never write namespaces: shared attributes on tags keep plain names, and a collision between two extensions' shared attributes is a configuration error.

The test of the boundary: refrakt builds on Marquise using only these hooks. If refrakt needs a special case inside Marquise, the seam is in the wrong place.

Marquise is a layer frameworks stack on; it never owns the chain. Decided 2026-11-17 (notes/marquise-foundation.md, section 3, "An Astro content loader for Rivière"). Refrakt owns the whole chain (its own loader, router, layouts and adapters), so every framework has to be adapted to it. Marquise, and Rivière above it, supply only what a host framework lacks (typed, validated, writable content, and relations between documents) and leave the rest to the host: routing, pages, layouts, images, islands, the build. The test for a new feature, beside the scope rule for core (section 20 of the notes): does it take over something the host framework already does? If so, it belongs in the host, an integration, or refrakt.

What goes to Marquise

marquise (core)

PartTodayNotes
Parsingpackages/runes/src/parse.ts (indentation-tolerant, SPEC-170)small; Markdoc is an internal module of core (an import rule in CI keeps the rest of core from using it) and an ordinary pinned dependency, not a peer dependency (notes Y8a); front-end packages only when a second syntax arrives
The definition format and loadercomposed-rune.ts, rune-dir.ts, project-runes.ts, the input half of lib/composition.tsfrontmatter: attributes, content, computes, prepare, description; body: examples (SPEC-197). Templates are a host extension
The content-model resolverlib/resolver.ts (1,104 lines), types/src/content-model.tsalready depends only on Markdoc and types
Attribute validationattributes.tsfindings with ids, as refrakt validate returns them
The value vocabularyfunctions.ts, SPEC-195's registryfunctions (first, split, item, text, source() from SPEC-198) for computes, which is written in CEL with plain dot paths (revised 2026-11-21: SPEC-195 D1 and D8 reopened). Not output(), which belongs to presentations
The selector languagefield-match.ts (147 lines)@marquise-md/selectors, owned by Marquise (decided 2026-11-21, notes Q4): the grammar, Marquise's resolver for one record, and a public API for vocabulary that Rivière and third parties register; CEL reaches it through selects(). refrakt's data and collection both use it
prepare registrySPEC-194 D1–D3packages register stages by key; a definition names one
The preprocess hooklib/preprocess.ts (SPEC-141)with provenance (pasted content's origin, SPEC-197 D5) and the files each directive read; file#id addressing stays in core as the address form. tags/include.ts moves to a satellite (decided 2026-11-17)
The rune node and serialisationADR-049 decision 8; transform/src/serialize.ts, helpers.ts (isTag), html.ts (renderToHtml)plain data, safe to send from server to client
A plain presentationnewhow a definition renders with no component bound (open question 3)

Renderers: @marquise-md/react, @marquise-md/vue, @marquise-md/svelte, @marquise-md/astro

The generic halves of packages/{react,vue,svelte,astro}: drawing the tree, element overrides, the component registry, rune-node dispatch, typed props, recursive slots, and the wrapper hook. Not ThemeShell, layouts, route rules or behaviours.

Tooling

PackageFromContents
@marquise-md/clipackages/cli/src/commandsvalidate, reference (the grammar), format (SPEC-170 indentation), types (prop interfaces from definitions), examples (list and test)
@marquise-md/language-server + VS Code extensionpackages/language-server, packages/vscodecompletion, hover, diagnostics, go-to-definition, formatting; not inspector.ts
@marquise-md/testnew, from the example checks in SPEC-197 D2validate every example against its definition, compare expect, render through a bound component
@marquise-md/aipackages/ai (prompt building, write mode)prompts from the grammar and examples, filtered by role
@marquise-md/mcppackages/mcp, slimmedvalidate, reference, format, types, examples

Satellites

Revised 2026-11-17 (notes/marquise-foundation.md, section 20). Marquise core owns the seams (preprocess, computed values through prepare, render middleware), not the tools that plug into them. Everything outside core is a satellite: its own repository, its own versions, depending only on Marquise's published packages, never on workspace links or internal modules. The separation enforces the public contract: a satellite that needs a private import shows a missing seam.

The scope rule for core: a piece belongs in core only if the content model, validation, records or the write path cannot be correct without it, or every user needs it. Everything else sits behind a public seam.

First-party satellites are only those that prove a seam:

PackageFromWhenWhy
@marquise-md/schemalib/schema-table.ts, seo.ts, schema-row.tswith the first releaseschema.org rows work on input only and are independent of themes, so they fit the boundary cleanly, and published structured data is one of the strongest reasons to choose typed content over plain Markdown. Separate because not every user publishes structured data
@marquise-md/includetags/include.ts (182 lines, SPEC-141)with the first releasethe reference directive: proves the preprocess hook, with provenance and declared dependencies, on day one. Optional, since not every project assembles content from files
@marquise-md/composethe template half of lib/composition.ts, composition-placement.ts, slot-markers.ts (SPEC-145, SPEC-168)after the first releasethe template language without refrakt's vocabulary: {% slot %}, each, {% if %}, variants, {% fragment %}, values, and placing other definitions. A template places only definitions, which are drawn by their components, their own templates or the plain presentation, so SPEC-194 D11's rule holds with the user's definitions as the primitives. A component can still replace a composed definition's template (ADR-049), and the renderer sees nested rune nodes. Later because it is the least settled part (SPEC-168, SPEC-177 are drafts), the largest (about 3,000 lines), and tangled with schema rows that cross rune boundaries (SPEC-145 D19), which go to @marquise-md/schema first

Not Marquise's: data (tags/data.ts, data-pipeline.ts, data-adapters.ts, data-projection.ts, data-emit.ts, SPEC-103, SPEC-127), snippet (tags/snippet.ts, anchor.ts, mask.ts, languages.ts, invocation.ts, review-marker.ts, SPEC-131, SPEC-134) and the diff rune's algorithm (lib/line-diff.ts) stay in refrakt, which uses Marquise's public hooks for them from outside: the best test those hooks get. Earlier drafts planned @marquise-md/data and @marquise-md/snippet.

Why the preprocess hook is core and include is not. A content model reads a tag's parsed children, so anything that should count as a tag's content must be in place before the model reads it. Markdoc's own partial resolves at transform time, after that, so an included file could never fill a rune's fields. That makes the hook part of the content model; and with it, provenance (findings point at the included file, the write path redirects or refuses edits to included content) and declared dependencies (a directive names the files it read, for caching, hot reload and determinism). include is one user of the hook, 182 lines, and not needed by every project. Earlier (2026-11-12) this paragraph kept include in core; the hook was what the argument proved. In Marquise, refrakt's _partials/ becomes one root a host configures, not a built-in convention.

How @marquise-md/schema works when a component draws the markup. Recorded 2026-11-12. Refrakt's structured data has never depended on who draws the markup: the schema table stamps typeof and property on the rune's own output during the transform, and collectJsonLd (seo.ts:80) derives the JSON-LD from that tree, before the engine and the renderer run (lib/schema-table.ts explains why). In Marquise:

  • JSON-LD is built from the rune node. The node already carries the named values (attributes, computed values, slots), and the table maps names to schema.org properties. That is today's "rebuild from the bag" strategy as the only one; there is no stamping, and no resolving a name across data-name and data-field.
  • No RDFa in component markup. RDFa means what the page's structure says: a property belongs to the nearest enclosing typeof. A component decides that structure, so Marquise cannot vouch for it, and a slot placed outside the root or two entities' parts interleaved would publish something false. A component-drawn rune publishes JSON-LD only, the format search engines recommend. Refrakt keeps RDFa for runes drawn by its own templates, where it controls the markup.
  • Entity boundaries are rune boundaries. Each rune node may be one entity; a rune in another rune's slot is a nested entity, linked by the property the parent's table names for that slot (a recipe's steps as recipeInstructions, an FAQ's questions as mainEntity). Refrakt already stops at a nested data-rune (findAllByName, SPEC-146 D1); on the rune node the nesting is the data structure itself, so no component or theme can change it.
  • Sources across a composition wait for @marquise-md/compose. A template can place one rune's content inside another's (a character's portrait inside a card), which puts a property's source on the far side of a boundary (SPEC-145 D19, the reason for data-owner and data-slot). Without templates, 1.0 does not have that case.
  • The host places the JSON-LD. Marquise returns JSON-LD objects for each document; the host writes the <script type="application/ld+json"> into the head. Renderer packages may offer a helper. Cross-page @id links and not republishing embedded content (BUG-045) need the whole site, so they stay with the site layer.
  • The baseline checks the switch. The new path will differ from today's tree walk in places. contracts/seo-baseline/ records today's output, defects included, so every difference is shown and then accepted or fixed (SPEC-130).

Out of scope: the block editor (packages/editor). It stays with refrakt.

What stays with refrakt

  • The design vocabulary: primitives (section, attribution, frame, codeblock), group and its layouts, metablock, output(), SPEC-177's theme and site template lookup and the per-theme structure contracts. The template language itself moves later, as @marquise-md/compose; until then it stays here.
  • The engine and themes: packages/transform except the helpers listed above; universal attributes and their facets; config.ts; vocabulary; Lumina; tokens; contracts.
  • The rune library: core runes in packages/runes/src/tags and all plugins.
  • The site: packages/content (loading, routing, layouts, the cross-page pipeline, the entity registry), the collection, aggregate, relationships, xref and expand pipelines, registers, and data-resolve.ts. Despite its name, that is the sandbox's data binding: it runs after the pipeline and queries the entity registry. SPEC-194 D12's three data scopes split the same way: data files go with refrakt's data, $page and $site are host values refrakt fills, and the registry stays refrakt's.
  • Adapters: sveltekit, next, nuxt, astro (the site integration), eleventy, html.
  • Refrakt-specific tooling: inspect, contracts, gallery, the theme commands, i18n, stale, plan, create-refrakt, and the block editor.

What has to be split first

ModuleGoes to MarquiseStays with refrakt
lib/index.ts (the schema builder, 1,270 lines)building a schema from attributes and a content modeluniversal attributes, schema tables, header roles, slot markers, composition wiring
lib/composition.ts (2,673 lines)now: reading a definition's input (attributes, content, computes, defaults). Later, as @marquise-md/compose: template expansion and placementthe design vocabulary's tags and placement rules, reached only through the template-tag hook. Until the move, templates must not call refrakt's vocabulary directly, or extracting them becomes a rewrite
deferred-body.tscapturing a tag's source as a placeholder and expanding it laterwhen to defer (the registry), and the values supplied
reference.tsa definition's grammaruniversal attributes, vocabulary, schema rows (as a host extension to the output)
plugins.tsdefinition packages: definitions, prepare stages, file rootstheme config, pipeline hooks, layouts, CLI plugins
packages/typescontent-model.ts, serialized.ts, the definition-package part of package.tstheme, tokens, pipeline, config
The four renderersgeneric renderertheme shell and refrakt's wrapper
examples.ts, fixtures.ts, cli/src/lib/fixtures.tsexamples read from definitionsfixtures for native runes until they move

Decisions to make

  1. What a tag is called. Decided 2026-11-12: authors write tags; developers define shapes.

    Define a recipe shape in shapes/recipe.md. Authors write {% recipe %} in plain Markdown. Your Recipe component receives typed props.

    • Why not "rune". Svelte 5 calls $state and $derived "runes", and Marquise ships a Svelte renderer; the word also tells a newcomer nothing. Refrakt keeps "rune" as part of its character.
    • Two things, two words. What an author writes in a page is a tag, Markdoc's own word, so authors learn nothing new. What a developer defines (attributes, content model, computed values) is a shape: it says what the definition is, the shape content takes, and developers already speak of "the shape of the data". It is distinct and searchable.
    • It fits refrakt's own use. SPEC-168 D6 already calls reusable content structure a "shared shape" (file="shapes/profile.md#body").
    • The ladder in one sentence: every refrakt rune is a Marquise shape plus refrakt's extras (templates, a theme presentation, the design vocabulary).
    • Considered: "block" (the audience's own word, but inline tags are not blocks, Markdown already splits block from inline, and SPEC-197 uses "blocks" for a definition's body); "definition" (accurate for the file, clumsy for everything else); "component" (the very thing a shape maps to); gem-themed words (unclear; kept for the name and tools instead).
    • Knock-ons: the directory convention is shapes/; error ids and docs use "shape" and "tag"; frontmatter keys (attributes, content, computes) are already neutral and do not change. The rest of this spec says "definition" and "rune node" for refrakt's side; Marquise's own docs and APIs use "shape" (and a "shape node" where this spec says rune node).
  2. Templates. Revised 2026-11-12. Not in the first release; later as @marquise-md/compose. The template language is generic; what is refrakt's is the vocabulary it places (SPEC-194 D11: elements come only from primitives). In Marquise a template places only definitions, so a user's own definitions are its primitives, and refrakt adds its vocabulary through the template-tag hook. The first release ships components and the plain presentation.

  3. The plain presentation. Decided 2026-11-12: a shape with no component bound renders plainly, so content is never silently lost and a shape is useful before its component exists. Once it ships the markup is a public format, so it is kept as small as possible:

    <section data-shape="hero" data-align="start" data-media-position="bottom" aria-labelledby="mq-1-headline">
      <div data-slot="media"><img src="/img/dashboard.png" alt="The dashboard"></div>
      <div data-slot="eyebrow"><p>New in 2.0</p></div>
      <div data-slot="headline"><h1 id="mq-1-headline">Ship docs your team will actually read</h1></div>
      <div data-slot="blurb"><p>From Markdown to a polished site in minutes.</p></div>
      <div data-slot="actions">
        <ul>
          <li><a href="/docs">Get started</a></li>
          <li><a href="https://github.com/acme/docs">View on GitHub</a></li>
        </ul>
      </div>
    </section>
    

    Updated 2026-11-19 (notes, X12.4): the plain presentation keeps the source's semantics (a heading field as a heading at the author's level, paragraphs and lists inside their wrappers, the root labelled by its heading, role="group" when the root is a div, generated ids prefixed and numbered per page).

    • The root is the element plain: { element } names (default div), with data-shape and one data-* attribute per attribute: kebab-case, defaults included.
    • One data-slot wrapper per non-empty field, in content order. A block field holds its nodes as written, an inline or text field its content (SPEC-200 D1). An item list renders from each item's content (SPEC-200 D10), so the list appears as the author wrote it.
    • Nested shapes in a slot render recursively: through their component if one is bound, plainly otherwise.
    • No classes. Classes are a theme's (SPEC-196); the attributes are what a developer styles against.
    • data-slot keeps the meaning refrakt gives it: a composed rune's slot names are its published names (SPEC-145 D10c). data-shape follows decision 1.
    • An unbound shape is reported: marquise check (the renderer or integration) reports shape-unbound, so a forgotten component is noticed; a strict project makes it an error.
  4. Repository. Revised 2026-11-19 (notes/marquise-foundation.md, sections 21 and 22, X1 and X2): build the content-model revision in refrakt, then extract Marquise early, as 0.x, in its own repository (marquise-md/marquise), with refrakt as its first consumer. Rivière starts in its own repository, and plan is rebuilt on it. 1.0 is declared for each after a period of stability with at least one consumer besides refrakt.

    • Why not incubate until the seams hold (the earlier decision): seams prove themselves only by crossing a real boundary, so incubation cannot verify what it is meant to verify. Inside the monorepo any package can import anything, which is how @refrakt-md/runes reached 111 exports; and building everything first turns the move into a large, late migration that keeps slipping.
    • Building and freezing are different: 0.x allows a lot to be built while breaking changes are still allowed; semver from 1.0 means "we stopped breaking things", known only after living with it.
    • Development across repositories uses local links (npm link, file: dependencies) for a fast loop; refrakt's main pins released 0.x versions.
    • Not refrakt-shaped: neither project reaches 1.0 with refrakt as its only user. Marquise needs the proof outside refrakt (step 4 below); Rivière needs a consumer unlike plan, such as the Astro proof project or a different domain.
  5. Versioning. Refrakt's packages are versioned together (Changesets fixed mode). Marquise needs its own versions, with refrakt pinning a range.

  6. Licence. Refrakt is MIT; Marquise stays MIT.

  7. Names to secure early. On 2026-11-12, marquise, marquise-md and marquisejs were free on npm. The @marquise npm scope, the GitHub organisation and the marquise.md domain still need checking by hand.

  8. Attribute and field names. Decided 2026-11-12: kebab-case in shapes, camelCase in props, by one fixed rule.

    • Authors see attributes the way HTML spells them (media-position), as refrakt does for nearly everything.
    • Developers see JavaScript names (mediaPosition). ADR-008's renderers already convert this way (fromKebabCase), and Vue makes the same conversion between templates and scripts.
    • Field names follow the same rule (avatar-after becomes avatarAfter).
    • Generated types document both spellings, for example /** \media-position` in Markdown. Default "bottom". */`.
    • Two names that collide after conversion in one shape are a shape error, name-collision.
    • A camelCase attribute name in a shape is reported, so the rule stays one-directional. Refrakt itself is not consistent today (its datatable example writes pageSize=10).

Package names

Decided 2026-11-17 (notes/marquise-foundation.md, section 3). The npm scope @marquise exists with no public packages, so it is not available. Core is the unscoped marquise (free), and every other package is under @marquise-md, following @refrakt-md and the marquise.md domain: @marquise-md/react, @marquise-md/cli, @marquise-md/schema, @marquise-md/include, and so on. The corpus layer, Rivière, is its own project under @riviere-md.

Public contracts

Added 2026-11-13 from the brainstorm (notes/marquise-foundation.md, section 16, Z6). Semver protects only what is listed here.

Who depends on itContracts
Content authorsthe content syntax and Marquise's conventions (explicit slots {% slot "name" %}, file#id, example blocks); a library's shape vocabulary (the library's); a design language's dimensions (the kit's)
Shape and kit authorsthe shape file format, including extension namespaces and the info finding for one not installed; dimension and preset formats; the kit manifest; the migration format (after SPEC-189); the binding format; the template language, with @marquise-md/compose
Developersthe shape node (prop naming, slots, item records, the dimensions convention); generated type names and structure; host callbacks (values, files, resolveAsset, resolveLink, translate, icon, onFinding, presentFinding); middleware and the context API; the lookup node; the directive and prepare registries; each renderer's component contract
Machinesfinding ids, severities and message parameters; the published schema documents; edit operations; CLI commands, flags, exit codes and JSON output; MCP tools and resources
Browsers, stylesheets, search enginesthe plain presentation markup (decision 3); the structure of JSON-LD output
Everyone (behavioural)determinism: the same content, shapes, kit versions and host values give the same output, which also defines cache keys; the trust boundary of untrusted mode

Not contracts: internal module paths; message wording (the id and parameters are); annotations added in development or editor modes; the order of findings; anything refrakt-specific.

Rules:

  1. Semver across Marquise's packages; breaking a listed contract means a major release, with a codemod for content or an upgrade guide for code.
  2. Formats read by outside tools carry a format version: the published schema documents, the kit manifest, JSON output. Shape files do not; Marquise's major version implies it.
  3. Finding ids are never reused; a renamed id keeps an alias for a deprecation period.
  4. Markup and output change additively: a new data-* attribute is fine; renaming or removing one is breaking.
  5. Tightening untrusted mode can break content that passed before, so it is announced and treated as breaking; loosening is never silent.
  6. No experimental flags: anything public is on this list; anything not ready is not exported.

Enforcement, after refrakt's committed-and-checked pattern (contracts/structures.json with refrakt contracts --check, the structured-data baseline): a public TypeScript API report diffed on every pull request; snapshots of the finding catalogue, the schema formats and the plain presentation markup; a JSON-LD baseline; the hostile-content suite; round-trip edit tests.

Contracts Marquise depends on. Revised 2026-11-19 (notes Y8): Markdoc is Marquise's syntax, so Marquise depends on Markdoc's parser and AST, kept an implementation detail behind Marquise's own types. Whether Marquise's renderers are built on Comark's (React, Vue, Svelte, Angular, HTML, which draw Comark's serialisable document, not its syntax) is evaluated during 0.x; if so, Marquise consumes Comark's document format and renderer conventions internally, never exposing them (the shape node stays Marquise's contract), pins version ranges, runs a contract test against Comark on every upgrade, and tracks it as a risk. The fallback is refrakt's generic renderers.

Order

Revised 2026-11-19 (decision 4, and X1 and X2 in the notes). Earlier (2026-11-12) the order kept everything inside the monorepo until a 1.0 moved out; now Marquise leaves early as 0.x, and 1.0 waits for stability with real consumers.

  1. The content-model revision, built in refrakt (notes, section 17): combinators, as, value types, compact forms owned by child shapes, compiling down to the existing resolver and used by refrakt's runes, with the matching algorithm written down and a shape's analysis (SPEC-201). Lab work: the shape file is Marquise's core public format, so it is built and used before it is frozen.
  2. The read path extracted to marquise-md/marquise as 0.x: parsing, shape files, the revised content model, validation with finding ids and addresses, records with JSON Schema and the Standard Schema validator, generated types, the shape node, the plain presentation, the generic renderers (ADR-049). Refrakt switches to depend on it at once: its first consumer across a real boundary, and anything it cannot reach through the public API is a missing seam.
  3. Tooling on Marquise alone: validate, types, extract, format, the language server.
  4. A proof outside refrakt: a small example project on plain Markdoc and a framework, with no refrakt config, theme or engine. If it is not compelling, stop here.
  5. A parser and positions spike (notes X5) before anything writes: one inline value changed through each candidate parser.
  6. Rivière in its own repository, as 0.x, with plan rebuilt on it in refrakt. Plan writes as much as it reads, so this also designs the write path against a real user before it is frozen.
  7. Marquise 1.0, the read path (notes X1: records included; the write path, body blocks, kits, dimensions, bindings, middleware, deferred shapes, migrations and a second syntax after; minimal document shapes are in 1.0), once its API has been stable for refrakt and the proof project for a period. The docs site is built with Astro (decided 2026-11-13).
  8. Minor releases as features graduate, including the write path; Rivière 1.0 once it has a consumer unlike plan.

Risks

  • Focus. A second project needs its own docs, issues and releases.
  • Freezing the core. Once others depend on Marquise, the definition format and resolver stop being free to change. Cutting 1.0 from what is already settled, reserving the definition body, and adding everything else as minor releases is what makes the freeze affordable.
  • Marquise becoming a second refrakt. The pull to add "just one more" feature is what made refrakt hard to finish. The graduation rule and the "not for" list are the defence; the number of hooks is the early warning.
  • The lab drifting from the product. Refrakt must build on the released Marquise, not on a private fork of it, or graduation turns into a port.
  • Explaining the idea. Reinterpreting Markdown is obvious once used and unfamiliar before. The first page has to show it: Markdown in, typed props out.
  • Two sources of truth during incubation. Refrakt must not grow a private path around a hook while the seam is being cut.

Worked example: a hero in React

Recorded 2026-11-12. A hero shape adapted from refrakt's own (plugins/marketing/runes/hero.md), in Next.js with React. The content-model keys are the ones refrakt's resolver supports today, plus SPEC-200's as and from; the shape node, generated types and the React API are this spec's proposal. Decision 3 shows the same content rendered with no component bound.

Updated 2026-11-19: the shape file below uses the revised content model (notes, section 17; the matching rules are SPEC-201's) and plain: { element } in place of a top-level tag: (notes, section 6).

shapes/hero.md. Refrakt's design attributes (valign, collapse, height, aspect, content-place) and its universal-attribute defaults are gone: in Marquise the component owns the layout, and a developer adds only the attributes authors should control. The body is empty, as 1.0 requires.

---
description: Full-width introduction at the top of a landing page
plain: { element: section }
attributes:
  align:          { type: string, matches: [start, center, end], default: center, description: "Alignment of the text and actions" }
  media-position: { type: string, matches: [top, bottom, start, end], default: bottom, description: "Where the media sits" }
content:
  split: { by: hr }
  zones:
    - name: media
      sequence:
        media: { match: image, optional: true }
    - name: content
      primary: true
      sequence:
        eyebrow:  { match: paragraph, optional: true, as: text }
        headline: { match: heading, as: inline }
        blurb:    { match: paragraph, optional: true, as: inline }
        actions:
          match: list
          optional: true
          items:
            label: { match: link, as: text }
            href:  { as: url }                 # with template: "[{label}]({href})" (notes Q8)
---

content/home.md, what an author writes. "New in 2.0" is the eyebrow because it is a paragraph before the heading; the sentence after the heading is the blurb.

{% hero align="start" %}
![The dashboard](/img/dashboard.png)

---

New in 2.0

# Ship docs your team will actually read

From Markdown to a polished site in minutes.

- [Get started](/docs)
- [View on GitHub](https://github.com/acme/docs)
{% /hero %}

Generated types (npx marquise types). The type parameter keeps them framework-neutral; @marquise-md/react fills it with ReactNode. An attribute with a default is never optional; a text field is a string.

/** Full-width introduction at the top of a landing page */
export interface HeroShape<R> {
  /** `align` in Markdown. Default "center". */
  align: 'start' | 'center' | 'end';
  /** `media-position` in Markdown. Default "bottom". */
  mediaPosition: 'top' | 'bottom' | 'start' | 'end';
  media?: R;
  eyebrow?: string;
  headline: R;
  blurb?: R;
  actions?: { label: string; href: string; content: R }[];
}

// from @marquise-md/react
export type HeroProps = HeroShape<React.ReactNode>;

The shape node that reaches the renderer: plain data, safe from server to client.

{
  "$$mdtype": "Shape",
  "name": "hero",
  "attributes": { "align": "start", "mediaPosition": "bottom" },
  "computed": {},
  "slots": {
    "media":    [{ "$$mdtype": "Tag", "name": "img", "attributes": { "src": "/img/dashboard.png", "alt": "The dashboard" }, "children": [] }],
    "eyebrow":  "New in 2.0",
    "headline": ["Ship docs your team will actually read"],
    "blurb":    ["From Markdown to a polished site in minutes."],
    "actions":  [
      { "label": "Get started",    "href": "/docs",                        "content": ["…the list item as written…"] },
      { "label": "View on GitHub", "href": "https://github.com/acme/docs", "content": ["…"] }
    ]
  }
}

components/Hero.tsx. The component picks the heading element, makes the first action the primary button and routes links through Next's <Link>; the author still wrote a plain list.

import Link from 'next/link';
import type { HeroProps } from '@/.marquise/shapes';

export function Hero({ align, mediaPosition, media, eyebrow, headline, blurb, actions }: HeroProps) {
  return (
    <section className="hero" data-align={align} data-media={mediaPosition}>
      <div className="hero__content">
        {eyebrow && <p className="hero__eyebrow">{eyebrow}</p>}
        <h1 className="hero__headline">{headline}</h1>
        {blurb && <p className="hero__blurb">{blurb}</p>}
        {actions && (
          <div className="hero__actions">
            {actions.map((action, i) => (
              <Link key={action.href} href={action.href} className={i === 0 ? 'button button--primary' : 'button'}>
                {action.label}
              </Link>
            ))}
          </div>
        )}
      </div>
      {media && <div className="hero__media">{media}</div>}
    </section>
  );
}

app/page.tsx. Written out so every step shows; a Next.js plugin could hide the reading and transforming.

import { readFile } from 'node:fs/promises';
import { loadShapes, transform } from 'marquise';
import { Content } from '@marquise-md/react';
import { Hero } from '@/components/Hero';

const shapes = await loadShapes('shapes');

export default async function Home() {
  const source = await readFile('content/home.md', 'utf8');
  const { tree, findings } = transform(source, { shapes });
  if (findings.some((f) => f.severity === 'error')) throw new Error(findings[0].message);

  return <Content tree={tree} components={{ hero: Hero }} />;
}

When the author gets it wrong (no heading, align="left"), npx marquise validate reports with refrakt's existing error ids, in the editor too, and as data an AI can fix from:

content/home.md:1  error  attribute-type-invalid  hero: align must be one of start, center, end (got "left")
content/home.md:1  error  content-missing         hero: needs a headline (a heading); found a paragraph and a list

What writing it out settled: a field's element versus its content (SPEC-200 D1), two item fields reading one link (SPEC-200 D9), keeping the list as written (SPEC-200 D10), attribute names (decision 8) and the plain presentation's markup (decision 3).

Acceptance criteria

  • The content-model revision is built in refrakt and used by its runes, with the matching algorithm and a shape's analysis of SPEC-201
  • Marquise 0.x exists in its own repository (marquise-md/marquise) with the parser, resolver, definition input, validation and records, and refrakt depends on its published versions
  • Marquise 1.0 contains exactly the table under "What 1.0 contains", and a definition whose body holds anything but {% example %} blocks is rejected

When 1.0 is declared (decided 2026-11-19, notes Y3): when every contract it freezes has survived its hardest real user. Each box below is ticked during 0.x.

  • Content-model syntax: every refrakt rune Marquise covers is expressed in the revised format; SPEC-201's analysis has run over all of them, every finding fixed or acknowledged; refrakt runs with strict on; the proof project's shapes were written by someone reading only the docs
  • Addresses: a write-path prototype (not shipped) edits one attribute and one field by address through the chosen positions route; toPointer() and Standard Schema paths agree on the same records
  • Records and rich text: plan's records are exported and consumed by something that is not Marquise (Rivière's prototype, a DuckDB query or the Astro loader); record size is measured on refrakt's content; an opt-in tree member (notes Y11) is decided
  • Plain markup: snapshot tests, and an automated accessibility check over refrakt's site rendered with the plain presentation only
  • Shape node and renderer contract: the proof project renders through at least two renderers, React as server components and one other
  • Finding catalogue: snapshot-tested, every id documented with an example that triggers it
  • Published schema: at least one outside consumer uses it (Astro's createSchema, or a Standard Schema consumer)
  • Trust boundary: the hostile-content suite passes through every 1.0 renderer, in both modes
  • Examples: refrakt's fixture files replaced by {% example %} blocks in its definitions, every one validated against its shape
  • Document shapes: plan's entities are document shapes, with no wrapper tags, in Rivière's prototype; the Astro loader maps a collection to a document shape
  • Generated types: used by refrakt and the proof project, with type-level tests
  • CLI and JSON output: snapshot-tested, exit codes included
  • Enforcement in place: the public API report checked on every change, and snapshot tests of the catalogue, schemas and markup
  • Stability: two consecutive 0.x minor releases, at least eight weeks apart in total, with no breaking change while refrakt and the proof project depend on Marquise
  • During 0.x, every breaking change is listed in the changelog with migration notes, and comes with a codemod when it changes content

Rivière's 1.0 follows the same pattern: plan's rebuild complete, one consumer unlike plan, the Astro loader working, and its own stability period.

  • Every later feature arrives as a minor release, after its spec is implemented in refrakt
  • @refrakt-md/runes builds on Marquise through the hooks listed under "The boundary", with no special case for refrakt inside Marquise
  • Each framework renderer has a generic half with no refrakt dependency beyond the model, and a refrakt half that adds the theme shell and the wrapper
  • validate, reference, format, types and the language server run on a project that has definitions but no refrakt config, theme or plugins
  • An example project renders definitions with React components using only the model and the generic React renderer
  • A component-drawn rune publishes JSON-LD built from its rune node and no RDFa, and the structured-data baseline shows every difference from today, each accepted or fixed
  • The decisions above are recorded, each with its outcome, before any package is published under the Marquise name

References

  • ADR-048, ADR-049
  • SPEC-194, SPEC-195, SPEC-197, SPEC-198
  • SPEC-141: preprocess
  • SPEC-145, SPEC-168, SPEC-177: composition, templates and fragments, template lookup
  • SPEC-170: indentation-tolerant parsing and formatting
  • SPEC-131, SPEC-134: snippet anchors and review markers
  • SPEC-103, SPEC-127, SPEC-113: the data rune, per-row templates, project files
  • SPEC-130, SPEC-146: schema tables and the structured-data baseline, rune ownership