Markstage documentation
How to set up an Astro site for Markstage, write and publish with it, run the server for a team, and connect other systems through its API.
Guides
Writing with Markstage
How writers use Markstage: open and start articles, add blocks, save and go live, use the Library, fix links, check SEO and bring back an older version.
markstage.config: every key
Set up an Astro site for Markstage in one file: collections, page URLs, settings fields, frames, page types, topics, forms, media and the editor canvas.
Deploying Markstage
Run the Markstage server next to your static site with Docker compose, or with systemd and nginx: data dir, config, the built editor, previews and backups.
Markstage with Docker
Run the Markstage server image next to your site with one docker run or compose: what happens at start, folders, settings, secrets, updates and tests.
The starter site
Start a new site from the Markstage starter: a small Astro blog with Markdown posts, an MDX guide and the editor set up, made with one script from a clone.
Environments: local, staging, production
How Markstage moves content and code between local, staging and production: branches, promotions with checks and screenshots, rules and a shared git remote.
Markstage server: security
How the self-hosted Markstage server protects a content site: sign-in, sessions, two-factor, roles, previews on their own origin, and the test behind each.
API and integrations
Markstage API (contract)
The HTTP API the Markstage editor and server share: sign-in, collections and entries, saves, publishing, media, users, revisions and the error shapes.
Editing MDX
How Markstage edits MDX: words typed on the page, components as cards with simple settings, and imports, exports and code kept as written.
The MCP server: AI agents
Connect an AI agent to Markstage over MCP: it reads the site and drafts as the person whose token it holds, and publishes only if an owner allows it.
AI suggestions
Ask a model for words you then read, change and save: image alt text, search titles and descriptions, summaries, and drafts for other locales.
The Library
One store of parts to use again: page templates, sections and snippets, synced or copied, kept as files in the repo, imported from WordPress or a web page.
Releases and share links
Put several changes live together, now or at a set time, with approvals and rules, and share a preview of a release or a draft with people who have no account.
Environments API
The server routes and command line behind environments: status, branches on the remote, plans that promote or sync content, and the checks that guard them.
Topics and internal links
Markstage keeps a map of every link in the site and suggests fixes both ways, so old pages link to new ones and new pages link to the right older ones.
Page frames and page types
Two settings a page keeps in its own file: the frame the site lays it out in (full width, reading or plain) and its page type, with the checks each type needs.
Authors
Ghost-style author profiles kept as JSON files in the site content: one per person, linked from posts by slug, with co-authors and an author page each.
Custom roles
Beyond the five built-in roles: a custom role for a translator, a reviewer or an editor who may not upload, limited to collections, locales and fields.
Permissions
Who may do what in Markstage, by role: owner, administrator, editor, author and contributor, the WordPress names, decided in one place on the server.
Single sign-on (OpenID Connect)
Let people sign in to Markstage with Google Workspace, Microsoft Entra ID, Okta, Auth0, Keycloak or any OpenID Connect provider, with passwords kept or limited.
Webhooks
Tell another system when something happens on the site: an entry saved or published, a media file added, the site gone live. Each webhook lists its events.
Importing entries and media
Bring entries and media files from another system as JSON: a dry-run plan first, nothing written or fetched, then the run of that plan as one job.
Forms, messages and alerts
The site forms post to Markstage on your own host: spam checks, limits, team mail and thank-you mail, the Inbox for messages and who hears about which alerts.
Translation status
For a site with several locales: whether each entry’s words are missing, outdated or done in each language, and the list of what still needs translating.
Integration fields
A Post settings choice whose options come from another system, such as a product catalogue or a CRM’s plans, fetched from a JSON address on a schedule.
Preview render
How Markstage shows a page with unsaved changes on the site’s own dev server, on an origin of its own, so author HTML never runs with the editor’s session.
Section gallery and “Edit this page”
Every section type the site’s pages use, drawn by the site’s own components, and an “Edit this page” link on the live site for people signed in to Markstage.