How the docs are built

DT One uses the same documentation layout and delivery approach as Fluxr Redemption. Markdown pages live in docs-site, VitePress builds the static site, and Laravel serves that build on the docs hostname.

Edit and preview

From the repository root:

npm run docs:install
npm run docs:dev

Update Markdown pages in docs-site. Navigation lives in docs-site/.vitepress/config.mts; the Fluxr logo, colours, fonts and error page live in its theme and public assets. Keep endpoint descriptions aligned with routes/api.php, request validation and response resources. Update docs-site/public/openapi.json when the API contract changes.

Build

npm ci
npm run build

The application build compiles the dashboard assets, installs the locked docs dependencies and runs VitePress. The docs output goes to public/docs and is excluded from Git. The deployment build must include development dependencies because Vite and VitePress are build tools.

For a docs-only rebuild after dependencies are installed:

npm run docs:build
npm run docs:preview

docs-site/README.md is a maintainer note and is excluded from the generated site. Local search, the sitemap, llms.txt, the OpenAPI download and the 404 page ship with the build.

Serve the docs hostname

Attach docs.dtone.fluxr.co.za to the same Laravel application as dtone.fluxr.co.za, with DNS and TLS configured. DOCS_DOMAIN defaults to that docs host. The global HandleDocsDomain middleware serves files from public/docs before dashboard routing.

The middleware resolves clean URLs such as /api, serves assets with their content types and returns the generated 404 page for missing files. A missing build returns HTTP 503. Requests to the app hostname continue through normal Laravel routing.

Changing DOCS_DOMAIN also requires updating the public URL in VitePress configuration and robots.txt. Rebuild both docs and the Laravel configuration cache after changes. A successful local build does not establish that DNS, TLS or the deployed application is configured.

Verify changes

php artisan test --compact tests/Feature/HandleDocsDomainTest.php
npm run docs:build
git diff --check

Inspect the built home, API, vendor setup, pricing and error pages in the sidebar browser. Check narrow screens, navigation, search and the OpenAPI download before release.