Skip to content
SmartSite Assistant SmartSite Assistant

Run the Documentation Locally

The documentation is a separate static Astro/Starlight application. It does not need WordPress, a database, OpenAI, or runtime secrets.

The documentation project builds static HTML, CSS, search data, and sitemap files from the structured catalog and MDX routes. It does not connect to WordPress or OpenAI. Authors edit catalog source, regenerate routes/inventory, inspect the Starlight development view, then run type, content, link, and production-build validation before publishing.

Start with the smallest safe step: change into smartsite-assistant-docs. Do not consider the task finished before you use npm run preview for a production-like local check; this is where the configuration is tested in the context that truly consumes it.

What this feature does and when to use it

Section titled “What this feature does and when to use it”

Use local development for content editing, sidebar review, screenshot replacement, and production build verification.

Use this feature in the following situations:

  • You are correcting or extending a guide after a source-code audit.
  • You need to preview navigation, search, responsive layout, or screenshot replacement locally.
  • You are preparing the exact static dist output for deployment.

Where to find it

Section titled “Where to find it”
WordPress locationDocumentation project → smartsite-assistant-docs

Before you begin

Section titled “Before you begin”
  • Node.js 22.12.0 or newer (supported even-numbered release).
  • npm and enough disk space for node_modules.
  • No .env secrets; this static site has no secret runtime configuration.

Set it up step by step

Section titled “Set it up step by step”
  1. Change into smartsite-assistant-docs.
  2. Run npm ci for the lockfile-defined dependencies.
  3. Run npm run dev and open the local URL.
  4. Edit the catalog/content/components/styles.
  5. Run npm run check and npm run validate.
  6. Run npm run build and inspect dist.
  7. Use npm run preview for a production-like local check.

Fields, controls, and important values

Section titled “Fields, controls, and important values”

These commands support the documentation rather than the WordPress assistant, so they have no effect on AI responses. They matter because generated pages, search, links, and source-backed explanations must stay synchronized. Running the correct checks helps prevent an administrator from following stale or visually broken guidance when configuring response quality.

Fields, controls, and important values
Field, control, or statusWhat SmartSite Assistant does with itHow to use it and why it matters
npm run dev Starts Astro development mode with live reload. Start the live-reloading authoring server while editing content, components, or styles. It is intended for local review and does not represent the optimized production output or affect the WordPress assistant.
npm run check Runs Astro/TypeScript content and component checking. Run Astro and TypeScript diagnostics before building so invalid component props, imports, or content types are caught early. A clean result protects the documentation interface; it says nothing about plugin runtime behavior.
npm run validate Checks page/catalog/sidebar coverage, links, screenshots, assets, demo text, and likely secrets. Use the project-specific audit to catch missing pages, navigation mismatches, weak required sections, screenshot collisions, raw table regressions, broken source links, demo text, and likely secrets before publication.
npm run build Runs validation and creates static dist output with Pagefind and sitemap. Create the production-ready static site after regeneration and validation. This step also produces search and sitemap output; it does not deploy the files or modify WordPress.
npm run preview Serves the built static output locally. Serve the already-built output for a final local inspection of production behavior. Unlike development mode, this shows the static result that will be published, although the real reverse proxy and hostname still need separate checks.

How to confirm it is working

Section titled “How to confirm it is working”

Use a separate test session to confirm Run the Documentation Locally. This keeps existing login, browser storage, and response history from hiding the change, and it shows whether the result reaches the complete workflow rather than stopping at WordPress storage.

Practical example

Section titled “Practical example”

After changing a UI default, update the matching catalog page, audit matrix, report, and screenshot capture instruction before building.

Section titled “Recommended practice”
  • Change one part of Run the Documentation Locally at a time and keep a short record of the previous value and test result.
  • Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.

Important warnings

Section titled “Important warnings”

Common problems and focused checks

Section titled “Common problems and focused checks”
Common problems and focused checks
ProblemWhat to check and what to do next
Run the Documentation Locally is missing or does not match this guide. Confirm the plugin is active and the account can manage WordPress options. Regenerate source-derived files and run the complete documentation validation before publishing the result.
A change on Run the Documentation Locally does not produce the expected result. Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Regenerate source-derived files and run the complete documentation validation before publishing the result.

Commands

Section titled “Commands”

Install and develop

Section titled “Install and develop”
cd smartsite-assistant-docs
npm ci
npm run dev

Full validation

Section titled “Full validation”
npm run validate:all

Screen reference

Section titled “Screen reference”
Run the Documentation Locally
Capture
Show a local Starlight page with the sidebar, search button, theme control, and a rendered screenshot placeholder.
Show
Site title/logo, search, sidebar, page content, theme control, placeholder frame
Viewport
Desktop, 1440 × 900
Annotate
Use numbered callouts only for controls referenced in the procedure.
Redact
OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text
Section titled “Related guides”