Publishing this guide

Manual contents

Source and public home

Edit the Markdown in docs/sdapi. The public home is /common/doc/sd/, with README rendered as index.html; the companion NL API User Manual is built from docs/nlapi to the parent directory /common/doc/, and the NuML User Manual from docs/numlapi to /common/doc/numl/. Each manual's page header links to the others, and links of the form ../nlapi/chapter.md or ../numlapi/chapter.md in this guide's Markdown resolve to the other manuals' generated pages (and vice versa).

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 stylesheet is the shared common/doc/guide.css, copied beside the generated pages. Generated HTML is a build product, not a second editable copy of the manual. Repository source links point to GitHub's HEAD view.

Configure the header's NuWebKit website destination with websiteUrl in site.json, exactly as for the NL manual.

Build and preview

From the repository root:

npm run build:docs

This writes all three manuals — the NL guide to common/doc, this guide to common/doc/sd, and the NuML User Manual to common/doc/numl — without rebuilding applications. Serve the repository root with your usual local static server, then open /common/doc/sd/. 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/sd/. The profile builds render the current Markdown of both guides directly into dist/common/doc; they do not depend on a previous documentation build. The website landing page links to both manuals.

Validate before publishing

node --test scripts/build-docs.test.mjs scripts/build-dist.test.mjs testing/sdapi-guide.test.mjs

Build checks validate generated pages, local links/anchors, escaping, navigation, and integration into website profiles for both guides. The guide tests execute the tutorial's model and the SDMain reference example from this manual's Markdown against the real runtime, and verify the documented commitment, reset, integration, and stopping contracts and the reference member inventories. Also check a narrow/mobile viewport, keyboard navigation, a long reference table, and a tutorial code block in the browser, and follow the header cross-links in both directions.

Deploy with the existing website

Deployment is identical to the NL manual's: the existing static website process publishes dist, which contains both guides. See the NL manual's publishing chapter and the deployment runbook for environment and publication procedures. Verify the landing-page manual links, /common/doc/sd/, the tutorial, a deep heading link, and the cross-links between the two manuals on the deployed host. Publishing is a separate operator action; preparing this guide does not authorize or perform an upload.