stx init
Initialize a new Syntext documentation project.
Scaffold a new Syntext documentation project — a syntext.json, starter pages and a public/ folder for images.
Usage
directory defaults to the current folder (.). It is created if it doesn't exist.
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
| Flag | Type | Default | Description |
|---|---|---|---|
--name <name> | string | the 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 |
--create | boolean | false | Also create the project on Syntext and link it (needs stx login) |
--ci <provider> | string | — | Also write a CI workflow: github, gitlab or bitbucket |
--docker | boolean | false | Also write a Dockerfile for a self-hosted export |
--template <template> | string | default | Accepted for compatibility; it has no effect today |
Examples
Start on doc engine v2
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
The site starts on the v1 default theme, and docs/index.mdx is a plain Markdown page.
Create and link in one step
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).
stx init adds .syntext/ to .gitignore. If your docs live in .syntext/, remove that line so they're committed.
Generated Structure
With --preset:
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:
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
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:
Use stx init --create for new projects. This ensures deployment works immediately with stx deploy.