Skip to content

site: build Astro site and static docs - #154

Draft
tombl wants to merge 10 commits into
mainfrom
site-docs
Draft

site: build Astro site and static docs#154
tombl wants to merge 10 commits into
mainfrom
site-docs

Conversation

@tombl

@tombl tombl commented Aug 14, 2026

Copy link
Copy Markdown
Owner

What changed

  • rebuild the root site and documentation as Astro applications
  • keep the docs fully static and remove the old VM/editor runtime from documentation pages
  • use Astro’s built-in Shiki highlighter with github-light-default and github-dark-default
  • switch dark syntax colors exclusively through the native prefers-color-scheme media query
  • convert every site runtime script to TypeScript, with separate browser, worker, and service-worker library scopes
  • import the kernel devices from the public package root and remove the Vite resolve aliases
  • compile the root-scoped service worker during site development and builds
  • add static Cloudflare deployment and pull-request preview workflows
  • preserve the live/install browser machine and its Firefox fallback coverage

Why

The previous site and documentation implementation mixed product runtime, documentation-only VM assets, CodeMirror/Lezer highlighting, and hosting concerns. This consolidates the maintained site and docs on current main, keeps syntax highlighting build-time only, and leaves the generated documentation with no client JavaScript.

The first CI run failed deterministically because the checked-in Nix pnpm dependency hash no longer matched the combined lockfile. This revision records the actual dependency hash. The kernel already exports blockDevice and serveDevice from its public root, so the site now follows that API instead of compensating with Vite aliases.

The rebuilt layout also made an existing browser test assumption unreliable: it watched only xterm's visible rows for a shell prompt that late kernel output could scroll away. The site now exposes guest-agent-backed readiness through aria-busy, and the test waits for that stable state before exercising the terminal.

User and developer impact

  • low.land keeps the current browser machine behavior in an Astro-built site.
  • docs.low.land is a static Astro documentation site with light/dark Shiki output and Markdown mirrors.
  • code blocks follow the operating-system color preference without a theme script or persisted theme state.
  • Lezer is no longer a direct docs dependency.
  • browser globals cannot leak into dedicated-worker and service-worker typechecking.

Validation

  • pnpm --filter @lowland/docs check
  • pnpm --filter @lowland/docs build
  • pnpm --filter @lowland/site check
  • pnpm --filter @lowland/site build
  • nix build .#site .#docs --no-link
  • nix build .#checks.x86_64-linux.browser-tests-check-site-live --no-link
  • nix fmt
  • git diff --check
  • browser verification in light and dark appearances
  • 360 px viewport verification with no page overflow
  • generated documentation pages contain zero <script> elements

@github-actions
github-actions Bot temporarily deployed to preview-docs August 16, 2026 08:30 Inactive
@github-actions
github-actions Bot temporarily deployed to preview-site August 16, 2026 08:30 Inactive
@github-actions
github-actions Bot temporarily deployed to preview-docs August 16, 2026 09:35 Inactive
@github-actions
github-actions Bot temporarily deployed to preview-site August 16, 2026 09:35 Inactive
@github-actions
github-actions Bot temporarily deployed to preview-site August 16, 2026 10:06 Inactive
@github-actions
github-actions Bot temporarily deployed to preview-docs August 16, 2026 10:06 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant