PureStack CLI

The purestack command builds a static site from a content directory. It discovers Markdown and Regor MDX pages, creates routes and navigation, generates theme styles, copies assets, and builds a search index when enabled. The same command also runs a development server and prepares a clean folder for publishing.

Install purestack in your project with yarn add purestack. The commands below use the installed purestack executable through Yarn. Run them from your project root. You can also explore the repository's sample site.

Build a first site

Create this folder beside your project's package.json:

content/
  siteConfig.json
  index.mdx
  about.mdx
  assets/
    logo.png

The CLI requires siteConfig.json at the root of the directory passed to --content. Start with:

{
  "siteTitle": "Acme Docs",
  "logo": { "brand": "Acme Docs", "href": "/" },
  "style": { "theme": { "skin": "standard" } },
  "outDir": "../dist/site",
  "publishDir": "../dist/publish"
}

Save that JSON as content/siteConfig.json. The two relative output paths are resolved from content, so they point to dist/site and dist/publish beside it. Light and dark theme styles are generated by default. The Site configuration guide explains every setting, including navigation, search, sitemap, localization, and consent.

Now add a home page at content/index.mdx:

---
title: Welcome
description: Start here to learn Acme.
template: doc
nav:
  order: 0
---

# Welcome

Read the [about page](/about/) or start writing your own guide.

Add content/about.mdx with its own title and body. Then start the preview server:

yarn purestack serve --content ./content

Open the URL printed as serving at after the first build. With the default settings it is http://127.0.0.1:4173/. The server binds to 0.0.0.0 by default; pass --host 127.0.0.1 if it should listen only on your machine. If basePath is set in siteConfig.json, the printed URL includes it.

Understand the content folder

The CLI recognizes .md, .mdx, and .rmdx as pages. Both .mdx and .rmdx use the Regor MDX pipeline. .md also uses that pipeline by default; mdx.compileMdAsMdx can change how .md is compiled. See the Regor guide for markup and component usage.

Routes follow filenames and folders:

guide/index.md and guide/guide.mdx are alternative names for the same route; do not keep both. The build reports duplicate routes as an error. Page frontmatter supplies a page's title, description, template, navigation order, and layout choices. If a page omits template, PureStack uses the documentation template.

Files such as assets/logo.png are copied into the output folder with their relative paths intact. The root siteConfig.json and navigation files are inputs to the build, not public assets. You can place _nav.json in a folder for custom or hybrid navigation, and header.mdx or footer.mdx for shared page sections. The Site configuration guide shows how to enable and order navigation.

Commands at a glance

Every build command requires --content <dir>. The path is resolved from the working directory and must contain siteConfig.json.

Use yarn purestack --help or yarn purestack help to print the CLI's own usage summary. Options can be written as --content ./content or --content=./content.

build: generate static files

yarn purestack build --content ./content
yarn purestack build --content ./content --clean

build renders all pages, writes the theme CSS and favicon when configured, copies static assets, writes a build manifest, and creates a Pagefind index when search is enabled. It writes a sitemap and robots.txt only when sitemap generation is enabled in siteConfig.json. The command exits when the build finishes; serve the resulting folder with your static host.

--clean removes the configured outDir before rebuilding it. Use it when you need an output folder containing only files from the current build. Without --clean, PureStack keeps the directory and rewrites current outputs.

serve: preview and edit

yarn purestack serve --content ./content
yarn purestack serve --content ./content --host 127.0.0.1 --port 4300

The server uses port 4173 and host 0.0.0.0 unless you override them. It serves files from outDir, checks watched content changes, and reloads open pages after changes. Content changes are handled incrementally where possible; a change to siteConfig.json causes a full rebuild so its new settings are applied.

These options belong to serve:

Watching and browser reload are separate. For example, --no-reload is useful if another browser tool manages refreshes. The server displays page build errors as diagnostic pages so you can correct the source and continue editing.

publish: prepare a release folder

yarn purestack publish --content ./content

publish uses publishDir instead of outDir. It cleans that directory before building, minifies generated HTML and browser scripts, disables pretty printed CSS, and treats asset build errors as failures. It creates the same site content and optional search and sitemap outputs as build, according to siteConfig.json.

Point your deployment process at publishDir after a successful run. publish prepares files locally; it does not upload them. It accepts --content, with no separate --clean flag because cleaning is built in.

Choose the public URL

The output directory is a filesystem path; basePath is a URL path. For a site hosted under https://example.com/docs/, set this in content/siteConfig.json:

{
  "siteTitle": "Acme Docs",
  "basePath": "/docs",
  "outDir": "../dist/site",
  "publishDir": "../dist/publish",
  "sitemap": {
    "enabled": true,
    "baseUrl": "https://example.com"
  }
}

The home page stays at dist/site/index.html, but links and the development server use /docs/. Your production host must serve the published folder at /docs/. sitemap.baseUrl supplies the origin; PureStack combines it with basePath for sitemap and canonical URLs. See Site configuration for the full path and SEO rules.

When a command fails

The checked-in sample content is a larger working site. PureStack Studio uses a custom TypeScript runner to register its own components, styles, and templates before building; yarn frontend starts that site's development server.