markstage.config: every key

Not on npm yet: install from a clone. The @markstage/* packages are not published to npm. Clone this repository next to your site and link them, as the README's quick start shows (Option 2). Your site needs Astro 7.4 or newer. To see the editor first with nothing to install, try the live demo.

A site tells Markstage what it edits, and how to draw it, in one file at the project root: markstage.config.mjs, .js or .ts (the first found, in that order). Both sides read it with the same loader, @markstage/core/site-config:

• astro dev, through the @markstage/astro integration;
• the Markstage server.

Restart either one after changing the file. Mistakes stop the start with markstage.config: <what is wrong>.

The server's own settings (sign-in, git, publish commands, preview origin) are in its config.json, not here. See docs/DEPLOY.md; the preview's keys (preview.origin, preview.warm: the site's dev server started with Markstage and kept warm, preview.idleMinutes, …) are in docs/API-PREVIEW.md.

import { defineConfig } from '@markstage/astro'; // or '@markstage/core/site-config'; it only adds editor hints

export default defineConfig({
  siteName: 'My blog',
  collections: [{ id: 'posts', format: 'md', dir: 'src/content/blog', url: '/blog/{id}/' }],
});

Paths to modules and CSS that start with . are relative to the project root. Anything else is a package name or a site path.

Top level

Forms

A form on the site posts to /markstage/forms/<id> on the site's own host (the server's config.json siteHosts lists those host names; docs/DEPLOY.md "Forms"). What it keeps, checks and mails is set here. Messages go to the Inbox in the data dir (never the repo); docs/API-INBOX.md "Forms and the Inbox" has the answers and the limits.

forms: {
  contact: {
    label: 'Contact',
    fields: {
      name: { label: 'Name', required: true, max: 100 },
      email: { label: 'Email', type: 'email', required: true },
      number: { label: 'Phone', type: 'tel', required: true },
      comment: { label: 'Message', type: 'textarea', required: true, min: 14 },
      service_type: { label: 'Service type', max: 100 },
    },
    meta: { page: 'pageUrl', referrer: 'referrerURL', landing: 'landingURL', utmSource: 'u_source', utmMedium: 'u_medium' },
    service: 'service_type',
    honeypot: 'hp_website',
    started: 'started',
    thanks: '/thank-you/',
    reply: { subject: 'Thank you for reaching out', text: 'Hi {name},\n\nThanks for contacting {siteName}. …' },
    team: { subject: 'Inquiry from {name} from {siteName} website' },
  },
},

Collections

Each collection is a folder of entries. One file is one entry, and the entry's id is the file name without its extension.

fields maps each role to a frontmatter key. Dotted keys reach into objects, e.g. seo.title. A role set to null is not read.

url has two forms:

• A template: {id} is the file name, and {key} or {a.b} is a frontmatter or JSON value. Examples: '/blog/{id}/', '/posts/{slug}/', '{uri}' (the whole address is stored in the entry).
• A function ({id, data}) => string | null. Use it when the address depends on other files; for example, the pilot site looks up the post's topic.

group is a function ({id, data}) => string | null. The search groups results under its value, for example "Salesforce alternatives".

Menus

A JSON collection with the id navigation holds the site's menus: one entry, or one per language when the languages' menus differ (a language picker then shows). The editor has a Site menus screen (#/menus/<entry>; under Content in the drawer, and in an entry's ⋯ menu). Every list in the entry whose items all have a label is a menu, named after where it is: primary is "Primary", footer.company is "Footer: Company", a list inside a column titled "Company" is "Footer: Company" too. Items nest with children; a menu whose items have children is a tree, as deep as it is now (the site's header decides how deep it can show).

A site that names its pages its own way sets linkKeys on the collection: { id: 'navigation', …, linkKeys: { page: 'pages' } } reads "page": "about-us" as a link to that page, and writes a picked page that way (in the old key's place). An entry of a collection no key names (a post, when only pages have one) is then written as its address. An item moved into a list takes that list's shape: "children": [] where every other item has one (an item whose last child moved out keeps its []), none where none has. Keys that start with _ (_lock) always stay last.

An item links to an entry, "entry": "pages/about-us" (<collection>/<id>): the site turns it into the entry's address when it builds, so moving the page never breaks the menu. Anything else is an address, "href": "/blog/" or "https://…". With neither it is a heading that opens its list. The screen picks a page or post from a search (stored as entry) or takes a typed address (href); a typed address that is one of the site's pages offers to link to the page instead, and an entry whose page is gone shows "Missing page".

{ "primary": [{ "label": "About us", "entry": "pages/about-us" },
              { "label": "Services", "children": [{ "label": "Migration", "entry": "pages/data-migration" }] },
              { "label": "Blog", "href": "/blog/" }],
  "footer": { "company": [{ "label": "Contact", "entry": "pages/contact-us" }] } }

The screen reorders (drag, keyboard, the grip's menu), nests, renames, changes links, adds a page, post or any address, duplicates and deletes, with undo. Every change saves that one list, so the file changes only where the menu did; every other key of an item (cssClasses …) stays. An item with "_lock": { "move": true, "remove": true, "by": "the site" } can't be moved or deleted (docs/OPERATIONS.md "Locks"); the site ignores keys that start with _. The site reads the entry itself (e.g. getEntry('navigation', 'en') in Astro).

Post settings

settings lists the fields of the drawer behind the gear (?s=1). When a writer saves, only the keys they changed are rewritten in the file; every other line stays byte for byte. Without settings, the drawer shows slug, excerpt, tags, author and date, for whichever of those fields names.

Every field takes label, and may take hint (a line under it). A key is a frontmatter key; dotted keys are written as nested YAML.

Locales and hreflang

A site with locales serves a copy of every page per region or language, each under its own path prefix. One source file serves every copy, and a locale may rewrite its text when the site is built (spelling).

Validation: codes and prefixes must be unique, there may be only one default, and xDefault must be one of the codes.

Each page emits one hreflang link per locale and then x-default, the same set on every copy. The helpers in @markstage/core compute that set: localePath, alternates, localeOfPath and emitsHreflang.

hreflang: {robots, canonical} names the frontmatter keys the site reads for two cases where a page emits no hreflang:

• its robots value contains noindex;
• its canonical is another address.

Post settings then says so instead of listing links. Set these keys only if the site's pages follow that rule.

In the editor:

• the screen check has a Region switch (?region=<code>). It frames that locale's copy, through the preview route with ?locale=.
• For a locale with spelling, the editor counts what the spelling changes, lists it in the checks column and highlights it in the page.
• The translation status of every entry in every locale with its own title or description (missing, outdated or done) is read from git: docs/API-TRANSLATIONS.md.
• Post settings has a "Languages and regions" section: each copy's address (copy and open) and the hreflang set.

Editor

How images are written

A plain image stays plain Markdown: ![alt](../../assets/uploads/2026/10/chart.webp). An image with a caption, a width other than the first, or the decorative mark is written as a figure around the same Markdown image, so the site still processes the image as usual (Astro optimises it):

<figure class="wide">

![A dashboard with three boards](../../assets/uploads/2026/10/chart.webp)

<figcaption>The board view, after the import</figcaption>
</figure>

The caption is plain text (&, < and > escaped). A figure written any other way is kept as HTML, unchanged. Uploads go to media.dir/<year>/<month>/ and the content refers to them relative to the entry's file.

Worked example: the example blog

examples/blog/markstage.config.mjs uses no block packs, has one collection, and keeps the defaults everywhere else.

export default defineConfig({
  siteName: 'Example blog',
  collections: [
    {
      id: 'posts',
      label: 'Posts',
      format: 'md',
      dir: 'src/content/posts',
      hasStatus: true, // drafts and scheduling
      fields: { excerpt: 'description' }, // the blog calls its excerpt `description`
      url: '/posts/{id}/',
      frame: 'reading', // a post with no frame of its own or of its type
    },
  ],
  // full width, reading or plain (src/layouts/Base.astro draws each), and what a post is for
  frames: true,
  pageTypes: {
    types: [
      { id: 'guide', label: 'Guide', collections: ['posts'], frame: 'full', template: 'lib_guide-post', checks: [{ id: 'topic', label: 'A topic', field: 'topic', level: 'block' }] },
      { id: 'article', label: 'Article', collections: ['posts'], frame: 'reading', checks: [{ id: 'guide', label: 'Links to its guide', linksTo: { pageType: 'guide', sameField: 'topic' } }] },
      { id: 'legal', label: 'Legal page', collections: ['posts'], frame: 'plain' },
    ],
  },
  // authors as files (src/content/authors/), pages at /author/<slug>/ (src/pages/author/), co-authors allowed
  authors: { coAuthors: 'coAuthors' },
  compat: { collection: 'posts' },
  editor: {
    css: ['./src/styles/blog.css'],
    canvas: { articleClass: 'post', bodyClass: 'post__body' }, // as in src/layouts/Post.astro
  },
});

The Post settings drawer comes from fields: excerpt (description), tags, author and publish date. The author is picked from the blog's authors (docs/API-AUTHORS.md), whose hub and pages are in src/pages/author/. Post settings starts with the Page box: the post's type, its frame and what its type still needs; the guide template ships in markstage/library/template/lib_guide-post.json (docs/API-PAGE-TYPES.md). There are no locales, so the Region switch and "Languages and regions" do not appear.

Worked example: a two-locale business site

markstage.config.mjs of a business site with a Canadian and a US copy (abridged):

import { SITE } from './src/lib/seo/site.mjs';

export default {
  siteName: 'Example Co',
  siteUrl: SITE, // https://www.example.com
  // Canadian English at the root (x-default), a US copy under /en-us/. The files are written in US spelling and
  // the root respells prose at build, with the same function the editor imports.
  locales: [
    { code: 'en-CA', prefix: '', default: true, label: 'Canada', variety: 'Canadian', spelling: './markstage/spelling-en-ca.ts' },
    { code: 'en-US', prefix: '/en-us', label: 'United States', variety: 'US' },
  ],
  xDefault: 'en-CA',
  hreflang: { robots: 'seo.robots', canonical: 'seo.canonical' }, // Seo.astro's rule
  collections: [
    {
      id: 'posts',
      label: 'Articles',
      format: 'md',
      dir: 'src/content/blog',
      fields: { slug: 'slug' },
      settings: [
        { type: 'slug', key: 'slug', label: 'URL slug' },
        { type: 'image', key: 'cover.src', alt: 'cover.alt', label: 'Cover image', clears: ['cover.width', 'cover.height'] },
        { type: 'select', key: 'cluster', label: 'Topic', from: 'clusters' },
        { type: 'select', key: 'author', label: 'Author', from: 'authors' },
        { type: 'seo', label: 'Search engines', title: 'seo.title', description: 'seo.description' },
        { type: 'social', label: 'Social card', title: 'seo.ogTitle', description: 'seo.ogDescription', image: 'seo.ogImage' },
        // … excerpt, categories, tags, date, canonical
      ],
      // the address and the search group come from the post's topic cluster (src/content/clusters/*.json)
      url: ({ id, data }) => `${clusters().get(data.cluster)?.path ?? '/blog/'}${data.slug ?? id}/`,
      group: ({ data }) => clusters().get(data.cluster)?.title ?? data.cluster,
    },
    { id: 'pages', label: 'Pages', format: 'json', dir: 'src/content/pages', url: '{uri}' },
    { id: 'authors', label: 'Authors', format: 'json', dir: 'src/content/authors', fields: { title: 'name' } },
    { id: 'clusters', label: 'Topics', format: 'json', dir: 'src/content/clusters' },
  ],
  compat: { collection: 'posts' },
  editor: {
    lang: 'en-CA',
    css: ['./src/styles/tokens.css', './src/styles/base.css', './src/styles/prose.css', './src/styles/article.css', './src/styles/article-parts.css'],
    canvas: { articleClass: 'post post--rich', bodyClass: 'prose post__body' },
    packs: [{ markdown: './markstage/blocks/markdown.mjs', editor: './markstage/blocks/editor.ts', css: './markstage/blocks/canvas.css' }],
    pageData: './markstage/page-data.ts',
    links: './markstage/links.ts', // the booking link, and the selector of the site's booking popup
    favicon: '/favicon-32x32.png',
    preload: ['/fonts/geist-latin-wght.woff2', '/fonts/geist-mono-latin-wght.woff2'],
    aliases: ['/studio'],
  },
};

The site's own round-trip check (a script in its repo) keeps parts of this config honest against the site's own code:

• section 7: links.ts popup selector equals the site's booking-popup rule;
• section 8: the locales equal src/lib/seo/i18n.mjs, and every built article page emits exactly the hreflang set the editor shows.