docs: host documentation on GitHub Pages with VitePress

[robertsLando]

Summary

• Move README content into a proper documentation site built with VitePress, deployed to https://yao-pkg.github.io/pkg/ via GitHub Actions
• Split the README into 21 focused guide pages (getting started, targets, config, bytecode, compression, SEA mode, snapshot FS, native addons, ESM, API, troubleshooting, advanced)
• New SEA vs Standard page that leads with the stock-binary benefit and links the pkg-fetch elimination roadmap (Upstream pkg-fetch patches to Node.js core to eliminate custom binaries #231)
• Landing page with pkg identity — amber + pink palette sampled from the org logo
• DEVELOPMENT.md and docs/ARCHITECTURE.md canonical sources moved into docs-site/, root files replaced with stub pointers so there's a single source of truth
• README trimmed to install + quick start + links to hosted docs

Manual follow-up

After merge, enable GitHub Pages in repo settings:

Settings → Pages → Source: GitHub Actions

The workflow at .github/workflows/docs.yml will deploy on every push to main that touches docs-site/.

Test plan

• npm run docs:build inside docs-site/ — clean build, zero warnings
• All internal links resolve (VitePress dead-link check passes)
• Prettier clean on all new files
• 21 guide pages + landing + architecture + development all render
• Manual smoke test on deployed site (after Pages enabled)
• Verify SEA vs Standard page renders matrix correctly in both light and dark mode

Files

• docs-site/ — new VitePress site
• .github/workflows/docs.yml — build + deploy workflow
• README.md — trimmed
• DEVELOPMENT.md, docs/ARCHITECTURE.md — stub redirects

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR migrates repository documentation into a VitePress site and adds a GitHub Actions workflow to deploy it to GitHub Pages, while trimming the root README and replacing root docs with canonical stubs.

Changes:

• Add a new docs-site/ VitePress documentation site (landing page, guides, architecture, development docs, theme + config).
• Add a GitHub Actions workflow to build and deploy the docs site to GitHub Pages.
• Replace root README.md, DEVELOPMENT.md, and docs/ARCHITECTURE.md with pointers to the hosted docs / canonical sources.

Reviewed changes

Copilot reviewed 35 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/ARCHITECTURE.md	Replaced full architecture doc with a stub pointing to the canonical docs-site page.
docs-site/package.json	Adds a private package definition and VitePress scripts/dependency for the docs site.
docs-site/index.md	Adds a VitePress home/landing page with hero content and quick-start.
docs-site/guide/troubleshooting.md	Introduces a troubleshooting guide page with common runtime/build errors.
docs-site/guide/targets.md	Adds a targets/cross-compilation guide page.
docs-site/guide/snapshot-fs.md	Adds snapshot filesystem behavior and path mapping documentation.
docs-site/guide/sea-vs-standard.md	Adds SEA vs Standard positioning, feature matrix, and pkg-fetch roadmap page.
docs-site/guide/sea-mode.md	Adds SEA mode usage docs (simple vs enhanced) and trade-offs.
docs-site/guide/packaged-app.md	Adds a short guide for packaged-app CLI equivalence and references.
docs-site/guide/output.md	Documents output flags and debugging behavior.
docs-site/guide/options.md	Documents --options for baking Node/V8 runtime options.
docs-site/guide/native-addons.md	Documents native addon handling and cache configuration.
docs-site/guide/index.md	Adds the guide index/intro page (“What is pkg?”).
docs-site/guide/getting-started.md	Adds installation + CLI reference + examples page.
docs-site/guide/esm.md	Adds ESM support documentation and SEA-related note.
docs-site/guide/environment.md	Documents supported environment variables and examples.
docs-site/guide/detecting-assets.md	Documents asset auto-detection heuristics.
docs-site/guide/custom-node.md	Documents using a custom Node binary via env var.
docs-site/guide/configuration.md	Documents pkg config (scripts, assets, ignore) with examples.
docs-site/guide/compression.md	Documents compression flags and SEA-mode limitation.
docs-site/guide/bytecode.md	Documents bytecode behavior, reproducibility, and public-packages constraints.
docs-site/guide/build.md	Documents building base binaries from source and points to SEA direction.
docs-site/guide/api.md	Documents the pkg programmatic API usage.
docs-site/guide/advanced-windows-metadata.md	Adds advanced guide on post-processing Windows metadata with resedit.
docs-site/guide/advanced-debug-vfs.md	Adds advanced debugging guide for inspecting the virtual filesystem.
docs-site/development.md	Moves development/release/testing docs into docs site.
docs-site/architecture.md	Moves full architecture doc into docs site as canonical source.
docs-site/.vitepress/theme/index.ts	Adds theme entry importing custom CSS.
docs-site/.vitepress/theme/custom.css	Adds custom brand styling variables and hero image tweaks.
docs-site/.vitepress/config.ts	Adds VitePress site configuration (base, nav, sidebar, edit links, SEO/meta).
docs-site/.gitignore	Ignores docs-site build output and caches.
README.md	Trims README to quick start + links to the hosted docs.
DEVELOPMENT.md	Replaces root development doc with a stub pointing to docs-site.
.github/workflows/docs.yml	Adds build + deploy workflow for GitHub Pages using GitHub Actions.
.github/copilot-instructions.md	Updates contributor guidance to use docs-site/ as the canonical docs source.

Files not reviewed (1)

• docs-site/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

docs-site/guide/targets.md:1

• There’s an extra comma before the parenthesized platform, which reads like a punctuation mistake. Consider removing it for clarity.

[Copilot]

This page has multiple grammatical issues that make the developer documentation look unpolished (e.g., “create release”, “have build”, “runned”, “It install”, “Foreach”). Please proofread and correct these phrases (e.g., “create a release…”, “have built…”, “run”, “It installs…”, “For each…”).

[Copilot]

This page has multiple grammatical issues that make the developer documentation look unpolished (e.g., “create release”, “have build”, “runned”, “It install”, “Foreach”). Please proofread and correct these phrases (e.g., “create a release…”, “have built…”, “run”, “It installs…”, “For each…”).

[Copilot]

This page has multiple grammatical issues that make the developer documentation look unpolished (e.g., “create release”, “have build”, “runned”, “It install”, “Foreach”). Please proofread and correct these phrases (e.g., “create a release…”, “have built…”, “run”, “It installs…”, “For each…”).