/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

stx init

Initialize a new Syntext documentation project.

3 min read

Scaffold a new Syntext documentation project — a syntext.json, starter pages and a public/ folder for images.

Usage

bash
stx init [directory] [options]

directory defaults to the current folder (.). It is created if it doesn't exist.

Warning

stx init writes syntext.json and docs/index.mdx without checking for existing files. Run it in an empty folder, then copy any existing pages in.

Options

FlagTypeDefaultDescription
--name <name>stringthe directory name (my-docs in the current folder)Project name, used in syntext.json, the starter pages and the project --create makes
--preset <preset>string—Start on doc engine v2 with this preset: workbench, paper, console, atlas, plain, orbit, grid or margin. The home page is written with the home components
--createbooleanfalseAlso create the project on Syntext and link it (needs stx login)
--ci <provider>string—Also write a CI workflow: github, gitlab or bitbucket
--dockerbooleanfalseAlso write a Dockerfile for a self-hosted export
--template <template>stringdefaultAccepted for compatibility; it has no effect today

Examples

Start on doc engine v2

bash
stx init my-docs --preset paper

The site starts on the Paper preset. docs/index.mdx is a home page built from the home components — <Hero> with a <SearchBar>, <SectionCards> and <LatestUpdates> — with layout: wide, and docs/quickstart.mdx is the page its Get started link opens.

Default theme

bash
stx init my-docs

The site starts on the v1 default theme, and docs/index.mdx is a plain Markdown page.

bash
stx init my-docs --preset workbench --create

Creates the project on Syntext and writes its ID to syntext.json as projectId, so stx dev and stx deploy work right away. If you aren't logged in, the files are still written and the command prints the stx projects create command to run later.

Docs inside an existing repository

stx init always writes to directory. For docs that live next to your code, create a .syntext/ folder and run stx init .syntext — the CLI finds a config in .syntext/ or .stx/ before the repository root (see Configuration Files).

Note

stx init adds .syntext/ to .gitignore. If your docs live in .syntext/, remove that line so they're committed.

Generated Structure

With --preset:

text
my-docs/
├── syntext.json
├── docs.json
├── docs/
│ ├── index.mdx
│ └── quickstart.mdx
├── public/
└── .gitignore

Without --preset, the second page is docs/guides/getting-started.mdx instead of docs/quickstart.mdx. --ci adds .github/workflows/syntext-deploy.yml, .gitlab-ci.yml or bitbucket-pipelines.yml, and --docker adds a Dockerfile.

Configuration File

The generated syntext.json with --preset paper:

json
{
"$schema": "https://syntext.dev/schema/syntext.json",
"name": "my-docs",
"theme": "paper",
"navigation": [
{
"group": "Getting Started",
"pages": ["index", "quickstart"]
}
]
}

Without --preset, theme is "default" and the pages are ["index", "guides/getting-started"].

The $schema line comes first, so editors such as VS Code autocomplete every key and flag a misspelt one as you type. See $schema.

stx init doesn't write a colors block — colors is deprecated. To set your brand colour, pick a preset and set appearance.accent, or use themeOverrides on a v1 theme. A new project passes stx check with no warnings.

Output

text
✔ Syntext project scaffolded!
Next steps:
cd my-docs
stx login
stx projects create my-docs
stx connect <projectId>
stx dev
This will deploy a preview and watch for changes.
Run stx deploy to publish to production.

With --create, the first line is Project created and connected! followed by the project ID, and the login, create and connect steps are left out.

Linking to Syntext

If you skip --create, link later with the project's ID from stx projects list:

bash
stx connect <projectId>
Tip

Use stx init --create for new projects. This ensures deployment works immediately with stx deploy.

Was this page helpful? Yes No
Previous
Next
Product
Resources
Company
© 2026 SyntextBuilt with Syntext