Restructure repo and overhaul documentation (VitePress docs site)#1
Merged
Conversation
…taticdemo -> generator - internal/analyzer: new package owning the analysis surface (Analysis/ ServiceAnalysis/Readiness/HostRequirements/AssetAnalysis types, Adapter*/ Label*/Mode* constants, AnalyzeFile/Analyze, the six adapters, readiness, and suggestions). Imports internal/compose for the Compose model. - internal/compose: now model-only (Project/Service/PortSpec/VolumeSpec/ EnvFileSpec + LoadFile); parsePortNumber test moved to types_test.go. - internal/generator: renamed from internal/staticdemo; embedded runtime now lives at internal/generator/runtime (go:embed unchanged, relative). - Update internal/cli imports/usages, the esbuild outfile in package.json, and the runtime test asset paths to internal/generator/runtime. All Go build/vet/tests, runtime tests, and make smoke pass.
- git mv runtime -> web/runtime, studio -> web/studio, site -> web/site so all browser-facing code shares one home. - package.json: esbuild input web/runtime/src/app.ts (output path unchanged at internal/generator/runtime/app.js so the go:embed still resolves); test:runtime and test:smoke file lists point at web/runtime/test/*. - Fix repo-root-relative paths in the moved runtime tests (../../ -> ../../../). - Update Makefile studio target, .goreleaser archive globs (web/site/*, web/studio/*), and the build-pages-site / record-announcement script paths. Go build/vet/tests, runtime tests, make smoke, make pages, and goreleaser snapshot + checksums all pass.
- Add vitepress dev dependency and docs:dev / docs:build npm scripts. - docs/.vitepress/config.ts: base /pocketstack/docs/, nav and sidebar laid out for the new information architecture (guide, adapters, convert, deploy, reference, contribute, release-notes). ignoreDeadLinks is on for now and will be tightened once every page exists (Phase 4). - docs/index.md: VitePress home/hero page. - Wire the docs build into `make pages` (docs:build then pages:build) and have build-pages-site copy docs/.vitepress/dist into dist/pages/docs. - Add a Docs nav link on the landing site; gitignore the VitePress dist/cache. The legacy flat docs still render as pages for now; they are reorganized into the new structure in the next phase. docs:build, make pages, and the browser test all pass.
…rchitecture - Restructure docs into guide/, adapters/, convert/, deploy/, reference/, contribute/, and release-notes/ sections, with single sources of truth: the adapter matrix (/adapters/), the label reference (/adapters/labels), and the COOP/COEP header values (/deploy/hosting). Other pages link instead of duplicating. - Add the missing onboarding and reference pages: getting-started, installation, CLI reference, concepts + glossary (browser-native vs browser-only), troubleshooting, per-adapter how-tos, the manifest schema reference, the service-URL reference, a developer guide, and a release-notes index (+ a v1.0.0 entry). - Remove the 13 legacy flat docs (content migrated); move the LinkedIn announcement out of the published docs into marketing/. - Slim README to overview + install + quickstart that links into the docs; repoint CONTRIBUTING, CHANGELOG, and the landing-site links to the new paths; standardize GitHub URL casing (lowercase) and compose.yaml. - Enable strict VitePress dead-link checking (the build now fails on broken internal links) and update the goreleaser archive glob to docs/**/*.md. docs:build (strict), make pages, the browser test, go test/vet, and the goreleaser snapshot all pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
An aggressive repo restructure and a full documentation overhaul, delivered as a published VitePress docs site. This is docs + structure only — no CLI behavior change; all behavior is covered by the existing tests, which stay green.
What changed
Phase 1 — Go layout (
bcf153e)internal/composeintointernal/compose(the Compose model: types +LoadFile) and a newinternal/analyzer(analysis: adapter detection, readiness, suggestions, theAnalysistypes,AnalyzeFile/Analyze).internal/staticdemo→internal/generator; the embedded runtime now lives atinternal/generator/runtime/(thego:embeddirective and esbuild output path stay aligned).internal/cli, the esbuild outfile, and the runtime test asset paths.Phase 2 — Web layout (
d41784e)runtime/,studio/,site/under a singleweb/home; updatedpackage.json(esbuild input + test lists), the Makefile, goreleaser archive globs, and the build/record scripts.Phase 3 — Docs site (
027bdba)docs:dev/docs:buildscripts, anddocs/.vitepress/config.ts(base/pocketstack/docs/, nav + sidebar). Wired the docs build intomake pages(→dist/pages/docs/) and added a Docs link on the landing site.Phase 4 — Docs content (
78d60fe)guide/,adapters/,convert/,deploy/,reference/,contribute/,release-notes/./adapters/), the label reference (/adapters/labels), and the COOP/COEP header values (/deploy/hosting) — other pages link instead of duplicating.marketing/.compose.yaml.Constraints preserved
Go module path,
internal/cli(release ldflags),examples/(left in place), the public Pages URLs (/,/studio/,/demos/,/media/+ new/docs/), and theweb/runtime/src/app.ts→ esbuild →internal/generator/runtime/app.js→go:embedbuild chain.Verification (all green)
make release-check—go test,go vet,make smoke, goreleaser snapshot, checksumsnpm run docs:build— strict (build fails on broken internal links)make pages— 10/10 demos + the docs sitenpm run test:browsers— landing page, Studio analyzer, and demo iframe pass in Chrome and WebKitNotes
https://ramazankara.github.io/pocketstack/docs/once this merges tomainand Pages deploys.internal/analyzer/analyzer.gois one large file in the new package; it could be split into multiple files within the package (Go is indifferent to intra-package file boundaries). Deferred to keep this change build-safe.