Hex Composer Documentation

This repository contains the public documentation for Hex Composer, a video synthesizer you play rather than a video editor you configure.

The published site is available at docs.hexcomposer.com.

Local development

Hex Composer Documentation uses Starlight and requires Node.js 22.12 or newer.

npm ci
npm run dev

The development server prints the local URL. To validate the documentation and create a production build, run:

npm run check

Contributing

Edit this page opens a full-page Milkdown editor. Readers can send changes for review without a GitHub account. Describe a problem accepts reports. GitHub editing remains available for experienced contributors. See CONTRIBUTING.md.

The account-free service requires separate Cloudflare and GitHub App setup; see setup and operations. Local editor routes stay disabled until configured; unconfigured mirrors link to the account-free editor hosted on GitHub Pages through the canonical docs URL. Versioned manuals retain their online correction link. Run npm run test:suggestions for delivery and source-mapping tests, npm run test:editor for corpus and browser checks, and npm run suggestions:check to verify the Worker bundle.

Manuals shipped with Hex Composer

npm run build:release -- vX.Y.Z builds a complete manual at /vizard-docs/releases/vX.Y.Z/, with release identity, local search and a hashed file inventory in dist/manifest.json. The app build captures newest docs main once and keeps the generated bundle for every platform and release retry.

Current docs continue deploying on main pushes. App releases upload the already built manual.zip and manual.zip.json to matching docs releases. Deployment runs npm run assemble:archives after building current docs, copying those verified files unchanged into dist/releases. Never rebuild/restyle old manuals or replace published release tags/assets. The /versions/ page links to current and archived manuals; links from installed manuals are marked online.

Run npm run test:archives to check preservation and failure behavior. To deploy current docs explicitly: gh workflow run deploy.yml --repo plmn95/hxc-docs. The app repository owns publication credentials and the build/release procedure.

Hosting and link previews

Vercel serves the current manual at docs.hexcomposer.com. Current reading pages on every host use that canonical origin. The GitHub Pages deployment at https://plmn95.github.io/hxc-docs/ keeps serving the account-free editor and frozen release manuals; /edit/... on Vercel redirects to that editor. The canonical /versions/ page lists the existing frozen manuals without copying or rebuilding them. Vercel proxies /vizard-docs/releases/... to /hxc-docs/releases/... on GitHub Pages, so the frozen files retain their embedded asset and navigation paths unchanged. The GitHub Pages versions chooser also links through this compatibility proxy. The old plmn95.github.io/vizard-docs/ address is no longer hosted by this repository. Vercel fetches public release metadata at build time and fails the build if it cannot load it. Release/offline builds do not perform that request.

Every authored page has a content-specific description. Shared social preview, ICO/SVG favicons, an Apple touch icon, and crawler guidance ship with the manual. Vercel headers allow Starlight inline scripts/styles, Pagefind WebAssembly, and the existing suggestion service while preventing framing and object embedding. GitHub Pages does not support these custom response headers.