Appearance editor
Change your doc site's preset, colours, fonts and layout in the dashboard with a live preview, then publish as a pull request.
Settings › Appearance in the dashboard is where you change how your doc
site looks: pick a preset, set your accent, fonts and
layout, upload your logo and favicon, and see the result on your own pages
before anything is published. It edits the same theme, appearance,
themeOverrides, name, logo and favicon keys you'd write in
syntext.json by hand —
there's no separate design stored anywhere else.
Overview
Settings › Appearance opens on an overview of the current look:
syntext.json (or syntext.yml) path and
branch, or Saved in Syntext for a project without a repositoryFrom here you can change the preset or open the editor.
Preset gallery
Change preset shows all eight presets drawn live in your own accent and logo. Switch Thumbnail colour between Your accent and Black and white to compare layouts without colour. Dark first marks Console. Your organization's themes are listed alongside.
Nothing changes until you publish. Switching presets keeps your accent, logo and the settings you changed.
The editor
The editor is full screen: controls on the left, a live preview on the right.
| Section | What you set |
|---|---|
| Preset | Start from any of the eight presets, or an organization theme — Follow new versions, or Pin to a version |
| Colour | The accent, suggested accents, and Different colour in dark mode for a separate dark accent. Contrast checks run as you pick (see below). Default mode (Light, Dark, System) and Readers can switch light and dark |
| Typography | Headings, body and code fonts — suggested pairs or any Google Fonts family — the body size (15, 16 or 17 px) and density (Comfortable, Compact) |
| Layout | Header, navigation, Fold sidebar groups, table of contents, page frame, page width (Contained, Full width) and corners (None, Small, Medium, Large). The deprecated home layout (appearance.layout.home) isn't offered; one already in the file is kept until you remove it — see Home page |
| Components | Callouts, steps, code blocks, cards, tabs and API reference — each shows when it's changed from the preset |
| Illustrations | Show illustrations for empty, error and home art, with a preview of each state |
| Brand | Logo for light mode, logo for dark mode, logo type (Mark + site name or Wordmark only), favicon and site name — see Brand |
| Advanced | The file's themeOverrides, read-only — edit them in syntext.json |
Each control maps to one key in the appearance reference.
Colour
The accent is checked in both modes as you choose it, the same way the build checks it: link text on the page background needs 4.5:1, accent fills need 3:1. A failing check shows the ratio and the nearest shade of your colour that passes, which you can apply in one click. A failing colour is never blocked — it's your call. See Contrast.
When dark mode has its own accent, the file gets
"accent": { "light": "…", "dark": "…" }; otherwise a single colour.
Brand
Brand sets how your site names itself: the logo, the favicon and the site name.
Uploads
There are three upload boxes: Logo, light mode, Logo, dark mode and Favicon. Drop a file on a box or click Upload (Replace once a file is set). The file uploads straight away and joins your unsaved changes.
| File | Logos | Favicon |
|---|---|---|
| SVG | Yes | Yes |
| PNG | Yes | Yes |
| ICO | No | Yes |
| Largest size | 1 MB | 1 MB |
The type is decided by the file's contents, not its name. SVGs are cleaned on
upload: Syntext rewrites the file keeping only drawing elements, and removes
anything unsafe — scripts, embedded HTML (<foreignObject>, <iframe>,
<embed>, <object>), on… event attributes, and links or url(…)
references to anything outside the file. What's stored and served is the
cleaned file.
A file that can't be used is refused with a message under the box, for example:
| Problem | Message |
|---|---|
| Wrong type | logo.gif isn’t an image we can use. Use an SVG or PNG file. (the favicon adds ICO) |
| Too large | logo.png is 2.4 MB. Use a file up to 1 MB. |
| Empty file | logo.svg is empty. |
| Not an SVG inside | logo.svg isn’t a valid SVG. Export it again as a plain SVG, or use a PNG. |
| Broken SVG, or one with a DOCTYPE | This SVG can’t be used. Export it again as a plain SVG. |
| Not an admin | Changing the brand needs the project admin role. |
With no dark logo, the light logo is used in both modes (Uses the light mode logo).
Logo type
| Option | What readers see |
|---|---|
| Mark + site name (default) | The logo with the site name beside it |
| Wordmark only | The logo alone. Use it when the image already contains your name |
Wordmark only with no logo uploaded still shows the site name, and the editor warns you.
Site name
Shown next to the logo and in browser tabs. Left empty, the site uses the project name from Settings › General.
Saving and defaults
Brand changes go into the same draft as every other setting: they count as unsaved changes, appear in the Review and publish diff, and publish the same way — a pull request, a commit or a hosted save (see Review and publish).
For a project with a repository they're written to syntext.json (or
syntext.yml):
A single logo with Mark + site name is written as one URL
("logo": "https://…"). Changing the logo in the editor keeps anything else
you set on logo by hand, such as a
suffix; the logo is then written
in the object form so the suffix has somewhere to live.
A project without a repository keeps the same values in its project settings. With no logo or favicon set anywhere, the site uses the Syntext mark (Using the Syntext mark).
Live preview
The page picker has two groups:
Both show Light and Dark at Desktop, Tablet and Phone widths (phones have the Guide, Home and 404 samples).
The preview opens on Home — your own home page when Your pages lists
one — so a header change can be checked against the home it leaves alone. An
index.mdx built from the home components
previews with your site's data, the same as a build.
Your pages include your custom CSS, as your live site does; your head and body snippets don't run in the preview.
Your pages
Pick one of your pages and the preview shows it as your next build would publish it with the draft — your content, sidebar and table of contents, in your preset, colours, fonts, layout and brand. Colour, font, size, corner and density changes show at once; the page is then re-rendered with the rest of the draft.
To render your pages, the editor needs a production build made since real-page previews arrived:
| Your site | What the preview says |
|---|---|
| Never built | Build your site once to preview its pages, and shows a sample page meanwhile |
| Last built before this feature | Rebuild your site once to preview its real pages, and shows a sample page meanwhile |
| A page picked that's gone since the last build | This page is no longer in your site — pick another |
Limits:
Preview build goes further: it starts a real build of your site with the
unsaved settings and deploys it to a preview URL of its own
(https://appearance-preview-<your id>--<project>.syntext.dev). Each person gets one preview URL,
and a new preview replaces their last one. A preview build counts against your
plan's build quota like any other build. A project without a repository can be
previewed only after it has been published once.
Review and publish
Review and publish shows the exact syntext.json diff, a commit message
(prefilled — "Switch docs to the Paper preset", for example), and where the
change goes:
| Option | What happens | Who can use it |
|---|---|---|
| Open a pull request (default) | A branch with the change and a pull request against your docs branch. A preview build starts when it opens. Readers see the change once it's merged and deployed | Project admins |
Commit to <branch> | Commits straight to the docs branch and starts a build | Admins with deploy rights |
| Save and build | For a project without a repository: saves the settings to the project and starts a build | Admins with deploy rights |
The file keeps its formatting: JSON keeps its indentation and key order, YAML keeps its comments, and only the keys you changed are touched.
Deploy rights: the owner always has them. An admin has them unless the project has an approval gate whose approver roles leave admins out — then admins open a pull request. If GitHub refuses a direct commit because the branch is protected, the editor switches you to a pull request.
Guard rails
syntext.json changed on the branch
after you opened the editor, a notice says so. Compare shows what changed
on the branch next to your changes, and Rebase my changes puts your
edits on top of the new file. If you both changed the same value, your value
is kept.Phones and tablets
On a tablet the sections become chips above a stacked preview. On a phone the editor has Controls and Preview tabs.
Try doc engine v2
A site that is still on doc engine v1 gets a Try doc engine v2 card on the
Settings › Appearance overview. Pick a preset and Build a preview: Syntext
builds your current published site on that preset and deploys it to a fixed
link, https://v2-preview-<preset>--<subdomain>.syntext.dev, without changing
your repository or config. The card shows the build's progress and opens the
preview when it is ready. Switch to v2 opens the editor with the preset
chosen, so the change goes through the usual review and publish. A preview
counts as a build. Deprecation notice emails link to this card.
See Try Doc Engine v2 for the API.
Deprecation banner
When your site uses deprecated syntax, a banner
on the project overview and on Settings › Appearance names the file and line,
the replacement, the date it stops working, and the stx migrate command.
Fix automatically on the banner, open to every member, previews the rewrite — each file's changes before → after, a diff per file, and what won't be changed and why — then saves it with Create pull request (GitHub) or Save as draft (written in Syntext). Nothing is published until you merge or publish it. Also move to doc engine v2 (changes the site's look) is off by default. See Fixing them.
API
The editor uses the public Appearance API: read, validate, publish, preview, list preview pages, render a page, convert the home to content and upload brand assets — the same endpoints you can call from your own tools.