Web Editor
Edit documentation in the browser with live preview, writing aids, an Assistant that proposes changes, linting, and review workflows.
The web editor lets anyone on your team edit docs from the dashboard — no local setup, no git knowledge required. It works the same whether your pages are written in Syntext or live in a GitHub repository; only saving and publishing differ. Open your project → Editor (or press ⌘K / Ctrl+K anywhere in the dashboard and jump to it).
Features
@stx annotations) and set their props in the Preview tab, without writing MDX{@embed} symbols and @stx tags as you typehead.html in your _syntext/ folder, with completions and the same checks as a publishEditing in the Preview
The Preview tab is editable. Every change rewrites only the lines of the block it touches and lands in the same unsaved buffer as typing in Edit — so the unsaved badge, Save and Request review work the same way, and you can switch to Edit at any time to see the MDX.
/guides/keys or a URL. Select text, then click one. The bar also shows the source line the block writes to. Formatting is kept as **, *, backticks and [text](href).<CodeGroup>), pick with the arrow keys and Enter, and the component is inserted under that block with working placeholder content. The picker shows the MDX it will insert, coloured as in Edit.@stx — Code from @stx in the same picker searches the functions, classes and types your repository annotates with @stx, and shows each one's path, kind and doc comment. Pick one to insert {@embed src="path#name"} — the page shows that symbol's current source on every build, so the example never drifts from the code. See Embedding symbols in MDX.Note, Info, Tip, Warning and Danger and keeps the content. The foot of the card shows the component's opening tag as written.When the page doesn't compile, the preview pauses behind a This page can't render banner with the error and Fix with Assistant, which opens the Assistant and asks it to fix the open page. The preview comes back as soon as the page compiles.
Completions in Edit
The Edit tab suggests what a Syntext page can use as you type, from the same component catalogue your site is built with:
| You type | You get |
|---|---|
< and a capital letter | Components. Picking one inserts a complete, valid snippet |
| A space inside a component tag | That component's props, required ones first. Props already on the tag are left out |
prop=" | The prop's allowed values, or the icon names for an icon prop |
| The start of a line in the frontmatter | Frontmatter keys |
](/ | Paths of the pages in this project |
{@ | The {@embed src="…"} directive |
{@embed src=" | Your repository's @stx-annotated symbols as path#name, with their kind, summary and signature |
@stx (in a code sample) | Every @stx annotation tag, with what it documents |
Each suggestion is marked with what it is — C a component, P a prop or frontmatter key, V a value, F a page, S an @stx symbol — and page suggestions show the page's title. A component's docs sit beside the list, with its props and what Enter inserts (for example, Steps with three empty steps).
Hover a component or prop name for its description, props and defaults. Press Ctrl+Space to open suggestions where they don't appear on their own.
Symbols come from the symbol index: the editor reads up to 200 code files from the head of your project's branch and keeps the result for 10 minutes, so a symbol you just pushed can take up to 10 minutes to appear.
Inline checks and quick fixes
Edit checks the page as you type and marks problems in the gutter, in an inline card on the line and in the Lint tab:
| Check | Example | Quick fix |
|---|---|---|
| Unknown component | <Notee> | Use Note |
| Unknown prop | <Card titel="…"> | Use title |
| Value not allowed for a prop | <Endpoint method="Post" …> | Use POST — the message lists every allowed value |
| Unclosed code fence | A code block with no closing ``` line | None — the message tells you where to close it |
| Broken page link | [Keys](/guide/keys) | "Did you mean /guides/keys?" — Use /guides/keys |
| Unknown embed symbol | {@embed src="src/keys.ts#rotatekey"} | Use rotateKey |
Links and embeds are checked in the browser against your page list and the symbol index, a moment after you stop typing. Links to files with an extension, images and the home page aren't checked. Frontmatter, code blocks and inline code are skipped by every check.
A fix is offered when there is a close match — a different case, or a name a couple of letters off. Each card names the rule (component/unknown, link/broken…) and its severity, and the fix button says what it does. On an error, Ask Assistant opens the Assistant and asks it to fix that line.
Custom code files
The files of your _syntext/ folder — site-wide
CSS, scripts and head.html — open in the editor like pages:
style.css, script.js or head.html with
starter content. If the file already exists, the editor says so — open it
from the file tree instead.--stx-* variables and [data-stx="…"] hooks
are suggested as you type, with hover docs for each. See
Custom CSS.url() addresses, and tags a script or head.html may
not contain. JavaScript and HTML get syntax highlighting.head.html don't run in the Preview.head.html are off until
a workspace admin turns them on.Only workspace admins and owners can create, edit or delete scripts and
head.html; other members can change CSS files, and see this if they try to change a script:
Only workspace admins can change scripts and head tags in _syntext/. Ask an admin, or put styles in a .css file. Other files can't be created in
_syntext/: _syntext/ holds only .css files, .js files and head.html, directly inside it.
Saving works like a page: a draft revision in a project written in Syntext, a commit on GitHub.
The Assistant
The Assistant panel beside the editor reads your docs and proposes changes. It never saves or commits — every change it suggests is a proposal you review, and nothing is saved until you press Save (Save draft in a project written in Syntext).
Reviewing proposals
The Assistant only proposes components, props and values from the catalogue — a proposal that would add an unknown one is refused before it reaches you, and the Assistant has to correct it and propose again. When you ask it to fix a page, it checks the page, proposes the fix, and checks the result.
What it reads
@stx · <project> appears when your project has API endpoints documented from @stx annotations.The panel
read_file, create_file or run stx check) under its name, one per line, apart from the answer. A reply with more than five steps folds them into one line you can open.Limits
Over a limit, the editor shows an error; wait a moment and try again. See Rate limits.
Saving & Publishing
How a save works depends on where the project's pages live:
| Written in Syntext | GitHub | |
|---|---|---|
| The button | Save draft | Save |
| A save | Keeps your changes as a draft revision: Saved as draft. The live site doesn't change | Commits every changed file to the project's branch in one commit and starts a build |
| Going live | Publish in the toolbar builds and deploys the latest save | The build from the save deploys |
| Creating or deleting a page | A draft, like a save | A commit; the next save or push builds it |
⌘S / Ctrl+S saves either way.
Publishing a project written in Syntext
The toolbar counts the saves the site doesn't show yet — 3 changes not published — beside Publish (on narrow screens, Publish · 3). Select Publish to build and deploy; the button follows the build until it's live, then shows Published. A failed build leaves the site as it was, with your drafts kept. When the month's builds are used up, You've used this month's publishes explains your options, and your changes stay saved as a draft.
History
In a project written in Syntext, History lists every save, upload and restore — for This page or All pages — marked Published or Draft. Open a revision for a per-file diff, then Restore the whole revision or Restore selected files. A restore is a new draft revision; tick Publish right away to publish it too. See History and restore.
Approval gates don't hold a save, and scheduled publishes aren't published automatically yet — see their notes on the Workflow page.
Conflict Protection
Saves are conflict-checked: if a teammate committed one of your files since you opened it, the whole save is refused and nothing is written. The editor shows a banner naming who saved the newer version, with Reload (drop your edits and load theirs), Compare, and Keep mine (save again over theirs) — see Save Pages.
Requesting Review
From the editor, click Request review on your pending changes — it opens the review form in Workflow › Reviews. Reviewers can approve, reject, or merge — see Workflow.
Git-Synced Projects
A project connected to GitHub through the Syntext GitHub App is edited in its repository:
To move a project written in Syntext to GitHub, or back, use Settings › Repository › Content source — see Move to GitHub. The Code from @stx picker and {@embed} completions need a repository: a project written in Syntext has no code to annotate.
Projects published with stx deploy have no stored pages, so the editor can't open them. Upload the same files to write them in Syntext instead.
Programmatic Access
Everything the editor does is available via the Pages & Content API and, for projects written in Syntext, the Content API — list pages, read/write MDX, lint, preview, batch-save, read the component catalogue and the symbol index, and chat with the Assistant.