/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Platform Appearance editor

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.

10 min read

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:

•
light and dark thumbnails of your site
•
the preset, accent (both accents, when dark mode has its own), fonts, mode, illustrations, and which values were changed from the preset
•
the organization theme, if the site uses one — the version and whether it follows new versions or is pinned
•
where the settings live: the syntext.json (or syntext.yml) path and branch, or Saved in Syntext for a project without a repository
•
Problems in syntext.json — anything the build would warn about

From here you can change the preset or open the editor.

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.

SectionWhat you set
PresetStart from any of the eight presets, or an organization theme — Follow new versions, or Pin to a version
ColourThe 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
TypographyHeadings, body and code fonts — suggested pairs or any Google Fonts family — the body size (15, 16 or 17 px) and density (Comfortable, Compact)
LayoutHeader, 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
ComponentsCallouts, steps, code blocks, cards, tabs and API reference — each shows when it's changed from the preset
IllustrationsShow illustrations for empty, error and home art, with a preview of each state
BrandLogo for light mode, logo for dark mode, logo type (Mark + site name or Wordmark only), favicon and site name — see Brand
AdvancedThe 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.

FileLogosFavicon
SVGYesYes
PNGYesYes
ICONoYes
Largest size1 MB1 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:

ProblemMessage
Wrong typelogo.gif isn’t an image we can use. Use an SVG or PNG file. (the favicon adds ICO)
Too largelogo.png is 2.4 MB. Use a file up to 1 MB.
Empty filelogo.svg is empty.
Not an SVG insidelogo.svg isn’t a valid SVG. Export it again as a plain SVG, or use a PNG.
Broken SVG, or one with a DOCTYPEThis SVG can’t be used. Export it again as a plain SVG.
Not an adminChanging 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

OptionWhat readers see
Mark + site name (default)The logo with the site name beside it
Wordmark onlyThe 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):

json
{
"name": "Acme Docs",
"logo": {
"light": "https://api.syntext.dev/v1/brand-assets/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/3f9a1c2b7d4e.svg",
"dark": "https://api.syntext.dev/v1/brand-assets/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/a81e04c9f6b2.svg",
"type": "wordmark"
},
"favicon": "https://api.syntext.dev/v1/brand-assets/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/0c5d7e9a1b3f.png"
}

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:

•
Your pages, as of your last publish — your site's own pages, rendered with your unsaved settings
•
Sample pages — Home, Guide, API, Search and 404, drawn exactly as your published v2 site draws them

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 siteWhat the preview says
Never builtBuild your site once to preview its pages, and shows a sample page meanwhile
Last built before this featureRebuild your site once to preview its real pages, and shows a sample page meanwhile
A page picked that's gone since the last buildThis page is no longer in your site — pick another

Limits:

•
Content is from your last production build. Unpublished edits to your pages, and pages added since, don't show until the next build.
•
Code colours are from that build. Syntax highlighting was done when the site was built, so a change to code colours shows on the next build, not in the preview.
•
Scripts don't run in the preview, so interactive parts (search, Try it, tabs) are shown but don't respond.

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:

OptionWhat happensWho 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 deployedProject admins
Commit to <branch>Commits straight to the docs branch and starts a buildAdmins with deploy rights
Save and buildFor a project without a repository: saves the settings to the project and starts a buildAdmins 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

•
Unsaved changes — the header counts them, Discard drops them, and leaving the page asks first.
•
Someone else changed the file — if 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.
•
Validation — every change is checked as you make it, with the build's own messages.
•
Members — members see the overview and the editor read-only (View only), with Ask an admin. Changing the appearance needs the project admin role.

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.

•
Custom CSS — style a v2 site beyond the preset with --stx-* variables and data-stx hooks
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext