Skip to main content

GitHub Pages

TinyLoop wiki deployment is a CI-driven static-site publish pipeline, not a manually pushed artifact workflow. The wiki source of truth is wiki/, and deployment is orchestrated by .github/workflows/wiki.yml.

Deployment architecture​

At a high level:

  1. checkout repository
  2. restore/install Node dependencies for wiki/
  3. run Docusaurus build
  4. upload build artifact to Pages
  5. deploy via GitHub Pages environment

This design separates content changes from hosting mechanics and keeps deployment reproducible from git state alone.

Local parity with CI​

Use the same commands locally that CI uses:

cd /home/runner/work/tinyloop/tinyloop/wiki
npm ci
npm run typecheck
npm run build

Outputs:

  • static site: wiki/build
  • typecheck gate: TypeScript/Docusaurus config correctness

npm ci is preferred over npm install for release parity because it enforces lockfile-resolved dependency versions.

Base URL and repository topology​

Docusaurus config resolves URL/base path from repository context. This matters because TinyLoop can be published as:

  • user/org pages root (https://<owner>.github.io/)
  • project pages subpath (https://<owner>.github.io/<repo>/)

Runtime-configurable base-url logic prevents hand-editing config when repository ownership/name changes and avoids broken asset links after forks.

i18n build implications​

The build includes all configured locales (en, zh-TW, ko, ja).

Operational consequence:

  • missing locale-specific docs do not always fail build (depending on fallback behavior and broken-link policy), but they can degrade user experience via mixed-language fallback.
  • structural docs changes (sidebar/category/doc ids) should be validated against all locales, not just English page render.

Why GitHub Actions + Pages​

This deployment path is chosen for:

  • reproducibility (build from exact commit)
  • auditable release history in workflow logs
  • no local machine credential dependency for publishing
  • low operational overhead for documentation-only hosting

Trade-offs and limitations​

  • GitHub Pages is static hosting only; no runtime server-side routing logic.
  • build-time failures block publication, so doc config regressions can delay unrelated content updates.
  • dependency vulnerabilities in the Node toolchain do not directly ship to runtime users, but still affect CI hygiene and should be tracked.

Source-control boundaries​

Commit:

  • wiki/ source and config
  • workflow definitions (.github/workflows/wiki.yml)
  • lockfile (wiki/package-lock.json) when dependencies intentionally change

Do not commit:

  • wiki/node_modules/
  • wiki/build/

Keeping generated output out of git ensures deterministic rebuilds and cleaner review diffs.

Operational checklist before merge​

  1. npm run typecheck passes
  2. npm run build passes for all locales
  3. no accidental generated-file churn (especially lockfile) unless intentional
  4. sidebar/doc-id changes verified against route links and navigation
  5. workflow file still points to wiki/ working directory