hao-ai-lab-FastVideo/docs-site

FastVideo documentation

Blume builds the documentation and React cookbook at haoailab.com/FastVideo. This PR replaces the previous MkDocs site using the existing GitHub Pages publishing workflow.

Develop and validate

Read Documenting FastVideo for setup, commands, source ownership, and the per-page writing template. Use Node 24 and Python 3.12. npm run dev --prefix docs-site serves under /FastVideo. npm run build --prefix docs-site prepares the content and writes dist/. npm run preview --prefix docs-site serves that static build.

Edit canonical guides under docs/, the welcome page under content/, the model catalog in lib/fast-models.ts, and sidebar grouping in navigation.json. Preparation regenerates .generated/ and public/; neither is an editable copy.

The documentation structure plan records the new navigation and proposed page consolidations. URLs stay stable in this PR. Hardware and integrations sit beneath Run inference. Model-specific references sit beside their family recipes in the Cookbook tab. Hardware and runtimes gives readers a single starting point for CUDA, MLX and ROCm.

Build architecture

• scripts/prepare-python-docs.py uses Griffe to extract modules, classes, signatures, docstrings, and source directly from Python files. It never imports FastVideo or needs PyTorch. Only Griffe, Markdown, and PyYAML are installed from requirements-docs.txt. It also regenerates examples and serving metadata.
• scripts/transfer-docs.mjs rewrites links, preserves fragments, copies assets, and overlays the handwritten application pages. Canonical guides use native Blume callouts and React family cards; no migration converter runs during builds.
• migration-anchors.json is a frozen compatibility contract for the previous site's URLs and heading fragments. Tests check the published output against it. Do not regenerate it to hide missing routes or anchors.
• scripts/prepare-content.mjs builds and copies cookbook catalogs and assets. React model cards replace the old family selectors. Source commands and serving configurations remain owned by their checked-in recipes.
• .github/workflows/infra-docs.yml validates and uploads docs-site/dist/ with the existing Pages actions. Deployment runs only on main. The domain, environment and /FastVideo prefix are unchanged.

Homepage and catalog

The welcome page uses Blume frame mode for its centered logo and accessible heading. News comes from the first two dated entries under NEWS in the root README; projects come from its Awesome work section. The original introduction and key features come from canonical docs/index.md.

The star button fetches GitHub's public repository count on load and every five minutes while visible. Failed initial requests show "Star"; failed refreshes retain the previous count. No credentials are used. The Trendshift badge loads from Trendshift. The lab mark in assets/hao-ai-lab.png is the supplied image.

Fast Models uses family cards, setup links, family filters, search, and consistent checkpoint rows. The curated links were checked against the public Hugging Face API on October 16, 2026. Published weights do not establish runtime or hardware compatibility. Check the support matrix and matching setup guide.

Extend the cookbook

islands/Cookbook.tsx owns the React UI and its loading/edit state. Shared configuration behavior stays in docs/js/cookbook-config.mjs. The typed adapter in lib/cookbook.ts describes the part of that existing contract used by this UI. Read the API contract and recipe authoring guide before adding fields or recipes.

• Keep native serving YAMLs and docs/cookbook/recipes/ as the source of truth. Do not add another recipe database or hardcode field lists in the UI.
• Use getOptions for field metadata and resolveConfig for validated YAML, server commands, and client instructions. Clear generated output when invalid.
• The URL stores the selected deployment. Edit values stay local to the page; URL serialization of all edited values is follow-up work.
• Reset restores the baseline. Missing fields remain inherited. Explicit false, 0, and null keep their meanings. Switching deployments discards edits.
• Installation and deployment guides resolve against the current origin and deployment prefix. Family runbook URLs remain available in the Blume site.
• VRAM fit is unknown. Add a calculator or a verified-run badge only with the measurements and evidence contract described in #1949.

Blume builds the documentation shell with Astro. Components in islands/ are ordinary React; client = "load" enables hydration. components/ui/ contains editable shadcn components, components.json configures the CLI, and theme.css maps their tokens to Blume's light/dark palette. Blume supplies Tailwind and reads tsconfig.json aliases. Add components from this directory:

npx shadcn@4.21.5 add dialog

The two npm overrides keep Astro's React integration and React plugin aligned with the versions used by Blume 2.2.3. Without them, npm's resolver cycles between the integration's newer plugin and Blume's pinned plugin. Recheck and remove the overrides when upgrading Blume.

The initial dependency audit reports 10 transitive advisories in Blume's dependency tree, including its unused Vercel adapter and Markdown build dependencies. The ordinary npm audit fix does not clear them; review upstream fixes before production deployment. Do not apply npm audit fix --force, whose proposed replacement is blume@0.0.0.

Verify UI changes

npm run format:check --prefix docs-site
npm run check --prefix docs-site
npm run test:cookbook --prefix docs
npm run build --prefix docs-site
npm run validate --prefix docs-site
npm run test:content --prefix docs-site
cd docs-site
npx playwright install chromium
npm test

The browser suite starts a production preview. It checks edits and downloads, invalid-output suppression, reset, switching runtimes, retry, obsolete loads, keyboard editing, and mobile overflow under /FastVideo. Keep shared API tests in docs/tests/; add React interaction tests here. No serving process is launched.

Review and follow-up

This PR switches the existing Pages artifact from MkDocs to Blume when merged. The original routes and fragments are checked against the frozen migration manifest. Review CI and the catalog/sidebar on desktop and mobile before merging. The remaining cookbook design and editor coverage in #1949 can continue without keeping a second documentation build. The editorial consolidation proposals are listed separately in INFORMATION_ARCHITECTURE.md.