Skip to main content

Build and serve the documentation site

This guide explains how to build, preview, and serve the SkillFlaw documentation site as an independent service.

The documentation site is not mounted under /doc/ in the product runtime. Use it as a standalone site root, such as http://localhost:3030/ in local workflows or a dedicated docs domain in deployment environments.

Prerequisites​

Before working with the documentation site:

  1. Start from the repository root.
  2. Ensure Yarn is installed.
  3. Install the documentation dependencies with:

_10
make docs_install

The documentation workflow uses Yarn as the package manager and stores its local cache in docs/.yarn-cache.

Choose the right workflow​

Use the workflow that matches your goal:

GoalCommandResult
Preview doc source changes with hot reloadmake docs_devStarts the Docusaurus development server
Build static documentation outputmake docs_buildWrites the production build to docs/build/
Build and immediately serve standalone docsmake docs_serveBuilds docs/build-standalone/ and serves it
Start an existing built docs directory without rebuildingmake docs_start_onlyServes the existing output directory directly

Start the development preview server​

Use the development server when you are editing documentation content and want live reload.


_10
make docs_dev

Default behavior:

  • port: 3030
  • route shape: root path /
  • usage: source preview for documentation editing

Open the site at:


_10
http://localhost:3030/

Build the standalone documentation output​

Use the build command when you need a static site artifact for later serving or deployment.


_10
make docs_build

This command:

  • installs docs dependencies if needed;
  • runs the Docusaurus production build;
  • writes the static output to docs/build/.

Use this workflow when another service, container image, or hosting platform will take over the static files after the build step.

Build and serve the standalone docs in one command​

Use this workflow when you want the repository to rebuild the standalone docs output and immediately start the local static server.


_10
make docs_serve

This command:

  • builds the standalone docs output into docs/build-standalone/;
  • starts the local static docs server;
  • serves extensionless documentation routes from the standalone output.

Use this when the content must reflect the latest source state before startup.

Start an existing build without rebuilding​

Use this workflow when a valid static output already exists and you only want to start the service.


_10
make docs_start_only

By default, this serves the existing docs/build-standalone/ directory and does not run a new build first.

This is the preferred startup path when:

  • you already built the docs in an earlier step;
  • you want to restart the docs service quickly;
  • you need to verify an existing artifact without changing the output.

Common parameters​

The docs commands support the following common variables:

VariableDefaultUse
docs_port3030Port for docs development or static serving
docs_serve_out_dirbuild-standaloneOutput directory used by make docs_serve
docs_start_dirbuild-standaloneExisting built directory used by make docs_start_only
docs_base_url/Base URL for make docs_dev
docs_build_base_url/Base URL for make docs_build
docs_serve_base_url/Base URL for make docs_serve

Examples:


_10
make docs_dev docs_port=3040
_10
make docs_build docs_build_base_url=/
_10
make docs_serve docs_port=3040 docs_serve_out_dir=build-standalone
_10
make docs_start_only docs_port=3040 docs_start_dir=build-standalone

Edit documentation content​

Use:


_10
make docs_dev

This is the best option for authoring and reviewing source changes.

Verify a fresh standalone artifact​

Use:


_10
make docs_serve

This ensures the static output is rebuilt before serving.

Restart the docs service without touching the artifact​

Use:


_10
make docs_start_only

This keeps the existing built output unchanged and only starts the service.

Validation checklist​

Before treating the docs service as ready, confirm all of the following:

  • the site opens from the standalone root path, not from /doc/;
  • the port you selected is reachable;
  • the expected build directory exists before using make docs_start_only;
  • links and localized pages render correctly after a new build.

See also​