Doc Site Features
Built-in reader features every Syntext doc site gets automatically — feedback, page navigation, AI actions, and machine-readable exports.
Every published Syntext site includes a set of reader-facing features out of the box. Nothing to install or configure — every build includes them.
Page Feedback
Each page ends with a "Was this page helpful?" widget. Reader votes are collected per page and surface in Insights › Feedback (Insights) and the Feedback API, helping you find pages that need work.
Previous / Next Navigation
Pages automatically link to their neighbors in the sidebar order, so readers can move through a section without returning to the navigation. The links follow your configured navigation groups.
Page Actions
On doc engine v1 sites, every page has an actions menu next to the title:
.md export of the pageOn doc engine v2 sites, the actions sit in the On this page rail: Ask about this page (when the assistant is on), Copy as Markdown, and Edit this page when the page has an edit link. Compact table-of-contents styles shorten them to Ask, Copy and Edit.
These are powered by per-page Markdown exports: every page.html has a matching page.md published alongside it.
AI-Readable Exports
Syntext sites publish machine-readable indexes for LLM tools:
| File | Contents |
|---|---|
/llms.txt | Index of all pages with titles and links |
/llms-full.txt | Full text of all pages in one file |
/{page}.md | Raw Markdown for any individual page |
Audience-gated pages are left out of llms.txt and llms-full.txt, a gated page's .md copy is gated like the page, and <AudienceGate> sections are cut from all three for every reader.
Point AI tools, crawlers, or the MCP server at these for accurate, up-to-date answers about your product.
MCP server
With the MCP server integration on, your site also serves a read-only MCP endpoint at /_mcp, so readers can search, read and ask your docs from Claude, ChatGPT, Cursor and other AI apps.
/.well-known/mcp describes the endpoint — its URL, protocol versions and whether sign-in is required — for MCP clients and registries.Agentic Mode (Ask Page)
Agentic Mode is an integration that gives your doc site a full-page agentic assistant at /ask — a conversational interface powered by the same assistant as the embedded widget. Enable it under Integrations › Agentic mode in your project; toggling it triggers an automatic redeploy. For a project deployed with stx deploy, that redeploy rebuilds the newest production upload; if the project has only preview uploads (or the monthly build quota is used up), nothing is rebuilt and the change takes effect on your next deploy.
When enabled, visitors can switch modes from two places:
/ask page slides back to Docs.What makes it agentic:
Memory and history are keyed by an anonymous visitor ID stored in the browser — no login required, and one visitor can never see another visitor's conversations. The persona, welcome message, and suggested questions all come from your AI assistant settings. Disabling the integration removes the /ask page, the header toggle, and the panel expand button on the next deploy.
Search
Full-text search is built in — press / or click the search box. Self-hosted builds include a static _assets/search-index.json so search works without the Syntext API (see stx build).
Doc engine v2
Sites that opt in to doc engine v2 with a preset get the features above in the v2 layout, plus the following. Sites on v1 are unchanged.
Pages open instantly
Clicking a link to another page of your site opens it in place, without reloading the page: the content, sidebar, table of contents, breadcrumbs and title change, and nothing else is fetched. Pages are fetched ahead of time when a reader points at a link, focuses it or touches it, and the pages next to the current one in the sidebar are fetched while the reader is reading, so most clicks show the next page in well under a tenth of a second.
css:
file, load as usual. So does the first page a reader opens after you publish
a new deploy, so they get its latest styles and scripts.Pages are also about half as heavy to download: the page code every page shares now loads once per visit instead of with every page.
Your own scripts run once per visit, not on every page; to act on each page,
listen for the stx:navigate event.
Phone and tablet layouts
Below 1180px wide the page switches to the tablet layout: a compact header with a menu button, a Search or ask field and the light/dark button. Below 768px it switches to the phone layout, where search is an icon. The layout follows the window as it resizes.
On both:
Search
Press ⌘K (Ctrl+K on Windows and Linux) from anywhere, or / when you aren't typing in a field. ⌘K also closes search.
<SearchBar /> in the page body opens the same
search on click, Enter or Space, and is in the tab
order./?q=…, which opens search prefilled — a shareable search link. With the
assistant off it only searches. See
Typing in the home search box.Table of contents
The table of contents (and a changelog's Recent releases) cuts an entry longer than two lines with an ellipsis; hover it to see the full text. A list taller than the window scrolls on its own, and fades at its bottom edge while entries sit below the fold.
Assistant panel
The assistant opens as a side panel on any page, from the search Ask row or from Ask about this page and Ask about this code. Answers stream in with their sources. You can stop an answer, vote on it, and reopen earlier chats from History. Chats are kept in the reader's browser.
Readers can drag the panel's inner edge to make it wider or narrower — from 360px up to 60% of the window (at most 900px); the default is 448px. The width is remembered in the reader's browser for your site, and double-clicking the edge resets it. The edge is keyboard accessible: focus it with Tab and use the arrow keys (16px per press), or Home and End for the narrowest and widest. On phones the panel stays full screen.
The panel's title is your assistant's name (aiPersona.name, default
"Assistant"). Its starter questions are the first four of
aiPersona.suggestedQuestions. Without suggested questions the starter list is
left out. See AI Assistant.
Agent mode
With Agentic mode on, the header shows a
Docs | Agent switch. Agent opens /ask with the page you were on as
context, so a first question can be about that page. Docs takes you back
to it.
On v2, /ask is a full agent workspace in your preset's style:
aiPersona.suggestedQuestions on the home screenHome page
Your index.mdx is the home page, and it shows what you write. Build it from
the home components — <Hero title>, the
home search box,
<QuickStart>,
<SectionCards>,
<ApiGroups>, <SdkList>,
<CommandList>,
<PopularPages>,
<LatestUpdates> and
<SupportCard> — each drawn in your preset's home
style and, used empty, filled from your site: sections, analytics, your
changelog page. Use layout: wide
for a home with no sidebar, or none to keep it. See
Home page.
Every v2 index page shows its own content — the preset's generated home
ended on 16 November 2026, and an index page with no content of its own gets a
build warning. See
Since 16 November 2026. With
no index page, / goes to the first page of your navigation.
API playground
v2 endpoint pages have a Try it console — see Try it on doc engine v2.
Protocol references
GraphQL, gRPC, AsyncAPI and webhook references are each one page in the v2 layout, under API Reference › Protocols:
| Reference | Page |
|---|---|
| GraphQL schema — operations and types | /graphql/ |
| gRPC services, methods and messages | /grpc/ |
| AsyncAPI events | /events/ |
| Webhooks — events, signature verification | /webhooks/ |
v1 split these into sub-pages (/graphql/types/…, /grpc/services/…,
/grpc/messages/…, /events/channels/…, /webhooks/events/…,
/webhooks/verification). On v2 those URLs redirect to the matching anchor on
the single page, so existing links keep working. A real page or one of your
own redirects at the same path wins.
GraphQL
pages: Int)
carries a nullable marker. Deprecated fields don't.! in the type and the operation's signature.v1 GraphQL references are unchanged.
AsyncAPI
The /events/ page shows the endpoint, then Connect, Client events,
Server events and Close codes. A section the spec has nothing for is
left out.
x-connection-flow extension; direction is c2s (client to server),
s2c or both, and steps without a message are dropped:Without it, the steps are built from the first server: opening the
connection (GET /path · Upgrade: websocket for ws/wss, otherwise
Connect · <protocol> <protocolVersion>), then one step per entry in
components.securitySchemes that the server's security requires, such as
Authorization: Bearer <token> or ?api_key=<key>. A scheme's
description becomes its step's note.
examples[].payload, a bare examples entry, or the payload schema's
examples / example. Without one, it's built from the payload schema:
each field's examples, example, const or default, else its first
enum value, else a placeholder for its type or format (0, false,
2026-01-01T00:00:00Z, user@example.com, …).x-close-codes extension at the root and on the
first server (the root's win when both list a code). Give an array of
{ code, reason, action }, or a map of code to reason. The What to do
column appears only when some code has an action:Language switcher
A site whose i18n names a second
language gets a languages chip in the header, next to the version control (or
in the header's free space in the index, path and simple headers), and
in the phone and tablet drawer beside the version select. Each language opens
the same page in that language, or that language's home when the page has no
translation. hreflang alternates list only the languages the page exists in.
See Translated documentation.
Announcement banner
The banner has a working close
button. A closed banner stays hidden on every page in that reader's browser
until you change its text or link; a deprecated version's notice can't be
closed.
Copy as Markdown in Safari
Copy as Markdown works in Safari: the copy starts inside the click, as Safari requires, while the page's Markdown is still loading. Browsers that don't support that get the Markdown once it arrives.
404 page
A v2 site gets a 404 page in its own preset, with the header and sidebar. It
shows the path that wasn't found, a search box pre-filled with the last part
of that path, and — from your site's search — up to three Did you mean
pages. Ask instead sends the question to the assistant, and a button goes
back to the docs home. With appearance.illustrations: false the
illustration is left out.
A 404.mdx page in your docs still wins: the build uses it instead.
Version menu
On a versioned v2 site with two or more versions,
the header's version control opens a menu listing every version, with the
current one checked. Picking one opens the same page in that version — at /
for the default version, /<label>/ for the others. A deprecated version is
marked in the menu, and pages in it show its deprecation notice
(deprecationMessage) as a banner.
Changelog feed
A page whose path is changelog (or ends in /changelog) is laid out as a
changelog: its <Update> entries run down a date rail,
filter chips (All plus every tag used in the entries' tags) show only the
entries with that tag, and the table of contents becomes Recent releases,
listing each entry. A changelog page with no <Update> entries yet shows an
empty state.
New,
Improved, Fixed, Breaking and Changed are coloured; any other tag is
a neutral label. A heading that opens the entry becomes its title.description (or the title) in forms like 9 November 2026,
2026-11-09 or Nov 9, 2026.<LatestUpdates>, show each entry on one line: its date,
its version, its label and its title, which ends in an ellipsis when it's
too long (hover for the full title) and links to the entry. A short,
version-like title (v2.4.0, API 2026-10-21) or a version tag (v2.1.0)
is the version, and the entry's first heading is its title; any other title
is the row's text, with no version column. The label is the first coloured
tag, else the first tag as a neutral label, else none. On phones the date
and label sit above the title.title="June 2026" → #june-2026, title="v2.4.0" → #v2-4-0); a title used twice gets -2, -3, …
on the later entries. The link icon beside an entry puts its anchor in the address
bar and copies the URL.<changelog path>/feed.xml (/changelog/feed.xml), linked as RSS feed
from the filter bar, which now shows even when no entry has tags. Every page
of the site carries <link rel="alternate" type="application/atom+xml">
pointing at it, and robots.txt lists it as a Sitemap:. <AudienceGate>
sections are cut from the feed for every reader, and the feed of an
audience-gated changelog page is gated like the page. See
Updates.Gated pages and sign-in
Links to audience-gated pages — in the sidebar, previous/next and the table of contents — are hidden from readers without access, as on v1, and the 404 page and the gate and sign-in pages below never show them to anyone. The audience gate, password page, invite-only sign-in and the "not deployed yet" preview page are drawn in the site's preset (after the site's next build). See Audience gating.
Your appearance, everywhere
Every appearance field — accent,
mode, fonts, size, corners, density, width, the light/dark toggle and
illustrations — and your themeOverrides apply to every v2 page, including
search, /ask, the 404 page and the gate pages.
Memory controls
When the assistant remembers things about readers,
readers manage it from /ask:
None of these show when you've turned memory off for the project.
SEO Files
Builds generate sitemap.xml and robots.txt automatically from your navigation, plus per-page meta tags and Open Graph data from frontmatter.
Every production deploy also pings IndexNow automatically, so search engines that support it (Bing, DuckDuckGo, Yandex) re-crawl your changed pages immediately. The required key file is generated and hosted for you — no setup needed. Google discovers changes through the sitemap referenced in robots.txt.
URL resolution
Page URLs resolve in this order, so both flat and directory-style layouts work:
| Request | Serves |
|---|---|
/ | index.html |
/guide | guide.html, else guide/index.html |
/guide/ | guide/index.html |
/api/users | api/users.html, else api/users/index.html |
/v1.2-migration | v1.2-migration.html — a dot in a slug does not make it an asset |
Paths are case-sensitive, so /Guide and /guide are different pages.
Files you ship in public/ are served at the path they sit at, including names
containing spaces or non-ASCII characters (/images/my%20logo.png).
Paths beginning with _ are reserved for Syntext — don't put your own pages
or files there.
Not-found pages
A request for a page that does not exist is answered with your 404 page and a
real 404 status — never a 200, which would let search engines index the
missing page, and never a bare CDN error.
docs/404.mdx and it is used, rendered in your theme with your
navigation.404 responses carry X-Robots-Tag: noindex. A hostname with no site
configured, and a site with no successful build yet, each get their own page
rather than the site's 404.
Response headers
Every doc-site response carries:
| Header | Value |
|---|---|
X-Content-Type-Options | nosniff |
Referrer-Policy | strict-origin-when-cross-origin |
Strict-Transport-Security | max-age=31536000 (plus includeSubDomains on *.syntext.dev) |
Cross-Origin-Opener-Policy | same-origin |
X-Deploy-Id | the deploy the response came from |
No Content-Security-Policy or X-Frame-Options is set: doc sites run inline
scripts, and pages are embeddable in your own product. Content-Type comes
from the type recorded at build time, so fonts, video, PDFs and web manifests
are served correctly rather than as downloads.
Preview deploys
Branch previews are served at {branch}--{slug}-docs.syntext.dev. Every
preview response carries X-Robots-Tag: noindex and previews serve a
robots.txt that disallows all crawlers, so a preview can never compete with
your production site as duplicate content. Custom domains are not available for
previews.
Production and preview builds
A build is a production build when it builds the project's production branch: the Branch under Settings › Repository (repoBranch in the API), whatever its name — main, develop, trunk or production. Every other branch builds as a preview. Only when no branch is set do both main and master count as production.
Search and the AI assistant answer for the live production site, so only a production build of the default version updates them. Preview builds, the builds of older versions and stx build exports leave live search and the assistant unchanged; their build log says so.
Each preview has its own address, <branch>--<subdomain>.syntext.dev. When that first part would be longer than 63 characters (the DNS limit), the branch part is shortened and ends in a short code, such as …-page-m-e202f7--testing-docs.syntext.dev; shorter branches keep their exact address.
A preview gets search of its own instead: search on a preview URL returns that preview's pages, never production's. A preview's search is removed when its pull request closes or the preview expires, 14 days after the branch's last preview build, or when the project has more than 10 (the oldest goes first). The assistant always answers from production.
Skipped and degraded builds
A build is skipped as "Content unchanged" only when nothing it depends on changed: every file in the source tree (including public/, API specs and schema files anywhere in the repository, and _redirects.json), the project's settings, name, slug and custom domain, the plan, the Agentic Mode and Custom Scripts add-ons, and the Syntext renderer itself. Use a forced build to rebuild anyway.
A build that deployed but had a step fall short — the assistant wasn't updated, search kept the previous results, an API spec failed to load, and so on — is deployed with warnings. The warn lines are in its log, and the build carries the count and the stages that warned (warnings and degraded on Get Build).
Printing and PDF export
Every page carries a print stylesheet, so Print (or "Save as PDF") in the browser produces the page rather than a screenshot of the app around it.
What changes on paper:
<CodeGroup> of seven
languages shows one at a time, and a printed page has no way to reach the
other six — so all seven print, each labelled with its tab name.<Tabs>, <Accordion> and <Expandable> bodies print open for the same
reason.On an API reference page the request/response rail is not printed. The rail holds copies of the samples that are already in the body of the page, and those originals print in the order they were written.
Nothing here is configurable, and nothing about it changes what a page looks like on screen.
Accessibility
The page templates that generate every doc site are audited against WCAG 2.2 AA with axe-core before each platform release, across both templates, light and dark, phone and desktop widths, left-to-right and right-to-left, and with JavaScript on and off. You do not run anything: the guarantees below ship with your site.
What that guarantees on a shipped site:
<CodeGroup> are a real tablist: arrow keys,
Home and End move between languages, and the group is one tab stop
rather than one per language.Tab cycles within it, Escape closes it, and focus returns to whatever
opened it. While it is closed it is out of the tab order entirely. Its
answer streams into a live region, so it is announced as it arrives.Nothing here is configurable, and none of it changes what a page looks like.
One known exception: the coloured HTTP method pills on API reference pages
(GET, POST, PUT, PATCH, DELETE) do not currently meet AA contrast
against their own tint. The method is always also given as text in the page
heading and the sidebar entry, so the colour is never the only way to read it.
Related
HTTP status chips
A table whose first column is an HTTP status code renders each code as a coloured chip — green for 2xx, amber for 4xx, red for 5xx — using the theme's status tokens.
No component or configuration is needed: it triggers on content shape. Only
first-column cells whose entire text is a 1xx–5xx code are affected, so a
table that merely mentions a number is left alone.
Grouped search results
On doc engine v2 sites, results are grouped by sidebar section instead, the group with the best match first and the rest in header-tab order (see Search under Doc engine v2 above). On v1 sites:
Cmd+K results are grouped by category — Endpoints, Guides, SDKs, Changelog, Pages. Groups appear in the order of their best result, so the group holding the closest match comes first: a guide that matches your words is not listed below unrelated endpoints. Endpoint results show an HTTP method chip, and section names keep their acronyms ("API Reference", "CLI", "SDKs").
The first row is always Ask: your query, which sends the question to the assistant. Enter still opens the top page result.
Category comes from the page path and frontmatter: pages under api/,
api-reference/ or reference/ are endpoints, guides/, tutorial/ and
getting-started/ are guides, and so on. Set category in a page's frontmatter
to override.
Arrow keys move through the rows in the order they are shown, Ask included.
Image zoom
An image in the body of a page opens in a full-screen overlay when clicked, and
closes on a second click or on Escape. It needs no component and no
configuration — any image in your content is zoomable.
This works identically on guide pages and on API reference pages.
Link safety in configuration
Every URL that reaches a rendered link — the header CTA, topbar and social
links, the sidebar status line, header tabs, footer columns, the announcement
banner, sidebar anchors, editUrl, and the logo and favicon paths — must be
http, https, mailto, tel, or a relative or absolute path. A URL using
any other scheme is dropped rather than rendered, and the link falls back to
#. Relative links, query-only links and #fragment links are unaffected.
The same rule applies to values that reach an inline style: page frontmatter
background and backgroundImage are emitted as single CSS declarations, and
anything that would end that declaration or reach outside it is stripped. An
ordinary colour, gradient or image path renders exactly as written.
It applies on every generated page, not only on guide pages: API reference
pages apply it to the GitHub link, social links, header tabs, the brand link,
the logo and the favicon, and a redirect target in _redirects.json is
checked the same way before the stub page links to it or navigates to it.
Names that come out of a specification are escaped wherever they reach a link
or an anchor — an OpenAPI operationId, a CLI command or flag name, a GraphQL
type or operation name, a WebSocket channel name. An operationId reaches
every page of a spec, because the endpoint sidebar lists them all.
Requests a build makes on your behalf
A remote OpenAPI url and a GraphQL endpoint are both fetched by Syntext
during the build. Both must be http or https on a public host. Private and
local addresses are refused, and the build log names the URL it would not fetch.
Limits on generated tables
An enum in an OpenAPI schema is listed up to 200 values, after which the list
ends with … and N more. Every table that renders a schema grows with its
enums, once per endpoint that references it, and nothing in a specification
bounds them.