On this page

Publishing this guide

Source and public home

Edit the Markdown in docs/nlapi. The public home is /common/doc/, with README rendered as index.html. The remaining chapters keep their base names with .html extensions. The build reuses Studio's locally vendored Showdown renderer; the delivered guide needs no JavaScript, CDN, or Markdown server. The companion SD API User Manual is built from docs/sdapi into the /common/doc/sd/ subdirectory, and the NuML User Manual from docs/numlapi into /common/doc/numl/, by the same command; each manual's page header links to the others.

The stylesheet lives in common/doc/guide.css. Generated HTML is a build product, not a second editable copy of the manual. Chapter links and heading anchors become local HTML links. Repository source and test links point to GitHub's HEAD view; they require internet access and may change as the repository evolves.

Configure the header's NuWebKit website destination with websiteUrl in site.json. It must be an absolute HTTP(S) URL without credentials. The current destination is https://nuwebkit.models.numerus.app/. After changing it, run npm run build:docs to refresh every generated page; the complete website build also reads this configuration automatically.

Build and preview

From the repository root:

npm run build:docs

This writes the current guide to common/doc without rebuilding applications. Serve the repository root with your usual local static server, then open /common/doc/. Opening the generated HTML directly also works for reading.

For the complete existing website build and preview:

npm run build:deploy-profile:production
npm run preview:dist

Open http://localhost:8788/common/doc/. The existing profile builds render the current Markdown directly into dist/common/doc; they do not depend on a previous documentation build. The website landing page links to the manual. Development and staging profiles include the same guide.

Validate before publishing

node --test scripts/build-docs.test.mjs scripts/build-dist.test.mjs testing/nlapi-guide.test.mjs testing/nlroot-utilities.test.mjs

Build checks validate generated pages, local links/anchors, escaping, navigation, and integration into website profiles. Guide checks execute the documented examples and inventory. Also check a narrow/mobile viewport, keyboard navigation, a long reference table, and a tutorial code block in the browser. No guide-only command publishes the site.

Designer redirects to the shared Studio entry point in Designer mode. Deployment and library tests cover that shared implementation, separate platform workspaces, and exact catalog filename casing. Run the full Node regression suite without exclusions:

node --test scripts/*.test.mjs testing/*.test.mjs

Deploy with the existing website

Use the project's existing static website deployment process with dist as its output directory. The repository's Cloudflare Pages configuration already selects that directory; no new hosting service or credentials are needed. See the existing deployment runbook for environment and publication procedures.

Commit/push the source changes through the normal release process before publication so GitHub source links can resolve. The HEAD links refer to the repository's default branch, not an unpublished local worktree.

Deploy the freshly built directory, not just Markdown. Any conventional static server can serve the same output. Verify the landing-page manual link, /common/doc/, a tutorial, and a deep heading link on the deployed host. Publishing is a separate operator action; preparing this guide does not authorize or perform an upload.