After the quickstart, you have a source project and a compiled Shoalrun CLI. Use the commands below from my-docs/, with SHOALRUN_CLI still pointing to the checkout's framework/dist/cli.js.
Prepare a release
Set site.origin in docs.config.yaml to your public HTTPS origin. Then audit the project and build it:
node "$SHOALRUN_CLI" audit docs.config.yaml
node "$SHOALRUN_CLI" build docs.config.yaml dist
Review the generated HTML, Markdown, and dist/documents.json. A build replaces its output directory; keep source files outside dist/. If it fails, use troubleshooting.
Choose a host
Choose a hosting route based on the artifacts and server features your site needs.
| Hosting route | What to deploy |
|---|---|
| Vercel | A source checkout containing the framework and your project; Vercel builds .vercel/output/. |
| Node server | The compiled site plus the built framework and its installed dependencies, as described below. |
| Another host | The compiled files plus routing and headers implementing the HTTP contract. |
For a site hosted at /docs, set site.basePath: /docs. The Node and Vercel adapters serve the prefixed routes directly. On a static host that mounts a directory at /docs, publish the build output's docs/ subtree as that directory's root. Static hosts still need a proxy or routing rules for Markdown content negotiation.
Node hosting
On a machine with Node and npm, obtain your committed checkout containing framework/ and my-docs/. From that checkout root:
npm ci --prefix framework
npm --prefix framework run build
node framework/dist/cli.js build my-docs/docs.config.yaml my-docs/dist
node framework/dist/cli.js serve my-docs/dist --host 0.0.0.0 --port 8080
The last command runs the server in the foreground. Configure your host's process manager to run it from the checkout root and restart it after a release. Route your public HTTPS endpoint to port 8080 using the host's proxy or load balancer. Preserve request Accept headers and response headers through that proxy. The Node server handles HTML, negotiated Markdown, explicit .md URLs, and discovery resources.
For a local check, use http://localhost:8080/install/ and http://localhost:8080/install.md from the minimal starter. Replace those paths with your own pages when you change the content.
Other hosts
A static upload alone does not establish Markdown content negotiation. Configure the host to serve the resources and page variants described in content negotiation, including Vary: Accept, content types, Markdown alternate links, redirects, and 404 responses. Use generated outputs to identify the files to deploy.
Verify the public site
From the checkout root, run the checker against your deployed origin:
npm --prefix framework run deploy:check -- https://your-docs.example/
Check a deployed site explains the result and how to pass a URL with a base path. A local build verifies files; this check verifies the host's responses.
Before sharing a page, check its SEO and social preview metadata, including the public share-image URL.
Next, put multiple versions on one site if you need several editions in one site. For branches, tags, and retained build snapshots, see use Git branches for separate docs sites.