The Markdown source in this repository is renderer-neutral OKF, but it can also build directly into a fast static browser site with navigation, search, and light/dark themes.

Recommended renderer

The documentation site uses Astro + Starlight:

• Markdown-first and statically generated.
• Fast local preview and deterministic production builds.
• Built-in documentation sidebar, previous/next navigation, breadcrumbs, search, and light/dark mode.
• Straightforward deployment under a base path such as /uec/.
• Compatible with the existing Markdown and YAML frontmatter; OKF provenance is preserved as extension metadata.
• Astro is already the technology behind the existing Invinsense documentation site, making future visual/platform integration straightforward.

Commands

Install dependencies once:

npm install

Prepare generated Starlight content, copying the canonical OKF pages and public images:

npm run docs:prepare

Start the local browser site:

npm run docs:dev

Open:

http://127.0.0.1:4321/uec/

Build the static production site:

npm run docs:build

Preview the exact production build:

npm run docs:preview

Build pipeline

1. tools/prepare_starlight.py reads the canonical OKF concepts.
2. Reserved OKF index.md files are omitted; the browser sidebar provides progressive disclosure.
3. Folder README.md concepts become Starlight section landing pages.
4. Bundle-relative .md links are converted to clean browser routes.
5. Image paths are copied under public/images and served beneath /uec/images/.
6. Starlight generates HTML, client-side search, sitemaps, and static assets under dist/.
7. The static dist/ directory can be deployed to the existing documentation host at /uec/.

Source of truth

The OKF Markdown remains the source of truth. The Starlight tree under src/content/docs/ and files under public/images/ are generated build artifacts and are not committed. Edit the canonical documentation, then rerun the OKF builder and documentation tests.

Deployment recommendation

Deploy the production output as a static site at:

https://documentations.invinsense.dev/uec/

Use the same host, domain, brand header, and product rail as the other Invinsense product guides. Keep /uec/ as the canonical public base path so deep links remain stable.