Docs reorg and updates - #939
Conversation
|
The changes in this PR will be included in the next version bump.
|
commit: |
|
unmarked as draft so it will deploy |
|
@pullfrog review this |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
Several navigation paths introduced by the page splits are broken, and the new Codex guide does not authenticate the interactive CLI as described.
Reviewed changes: This PR reorganizes the documentation into tabbed navigation, splits large hubs into child pages, preserves selected legacy URLs, expands the prompt builder, and fixes the varlock init --agent documentation URL.
- Add a tabbed Starlight sidebar: Introduces topic tabs, nested navigation groups, and sidebar state persistence that includes default collapsed state.
- Split major documentation hubs: Moves CLI, MCP, proxy, sandboxing, Kubernetes, and AI tool content into overview and child pages.
- Update navigation and discovery surfaces: Reworks integrations and plugins hubs, homepage tiles, page icons, prompt-builder links, and the Docker route.
- Preserve selected legacy links: Adds route redirects and synchronous hash redirects for moved hub sections.
- Fix agent initialization guidance: Removes the stray backtick from the local-encryption URL emitted by
varlock init --agent.
⚠️ Legacy deep links are only partially preserved
The redirect table covers the top-level examples in the test plan, but many headings moved from the old hubs have no mapping. Existing links such as /guides/proxy/#placeholders, /plugins/kubernetes/#authentication-options, and /reference/cli-commands/#output-formats-for-scripts--agents now open a hub with no matching anchor.
Technical details
# Legacy deep links are only partially preserved
## Affected sites
- `packages/varlock-website/src/components/CustomHead.astro:12-61` — `HASH_REDIRECTS` lists only selected moved headings.
- `/guides/proxy/#placeholders` — content moved to `/guides/proxy/rules/#placeholders` without a redirect.
- `/plugins/kubernetes/#authentication-options` — content moved to `/plugins/kubernetes/setup/#authentication-options` without a redirect.
- `/reference/cli-commands/#output-formats-for-scripts--agents` — content moved to `/reference/cli/load-and-run/#output-formats-for-scripts--agents` without a redirect.
## Required outcome
- Every heading removed from a retained hub URL continues to resolve to the corresponding child-page heading.
- Legacy links work for both trailing-slash and non-trailing-slash hub URLs.
## Suggested approach
Derive or complete each hub's redirect map from all headings moved into its child pages, rather than maintaining only the first-level section anchors used in the manual test plan.azure/gpt-5.6-sol ｜ 𝕏
|
Pushed commit Task list (5/5 completed)
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
varlock-website | 6ba6c07 | Commit Preview URL Branch Preview URL |
Jul 28 2026, 11:11 PM |
- flatten command reference into reference/cli/project - substitution surface + client compatibility into the split proxy pages - restore vite sections dropped on main - fix links broken by the moves, plus a few pre-existing ones
… under proxy Individual sandbox recipes are integration-shaped (some may get published packages), so they get their own Ecosystem heading at /sandboxes/*. The sandboxing concept guide is proxy-specific, so it becomes /guides/proxy/sandboxing. Old URLs redirect.
Group labels drop to the same size as their links, and bold is reserved for open groups so closed ones read as plain list items. On mobile everything steps down a size with tighter padding, and the tab switcher shrinks.
Every other tab is groups-of-pages; Getting Started was a bare page list, which Starlight styles as top-level headings. Wrapping the pages in a group makes the structure uniform and drops the CSS that was compensating for it.
5985975 to
7318279
Compare
📦 Bundle size✅ shrinks the bundle by 0.0 KB (−0.0%)
dist/ only; native binaries are versioned separately and not counted here. |
There was a problem hiding this comment.
Important
The new sandbox overview overstates the network containment provided by the listed recipes.
Reviewed changes: Reviewed the documentation and sidebar updates added after the prior Pullfrog fix.
- Ported current documentation updates into the reorganized structure: Updated moved anchors, restored Vite sections, and aligned links with the split CLI and proxy pages.
- Moved sandbox documentation into its final navigation locations: Placed proxy-specific concepts under
/guides/proxy/sandboxing/, moved individual recipes under/sandboxes/, and added redirects for the old routes. - Added the Sandboxes overview: Added an Ecosystem landing page and linked it from the proxy sandboxing guide and sidebar.
- Refined the sidebar hierarchy and mobile presentation: Renamed groups, compacted mobile spacing, kept group headings bold, and grouped Getting Started pages under
Start here.
azure/gpt-5.6-sol ｜ 𝕏
|
Updated the sandbox overview to make clear that filesystem, process, and network isolation varies by tool, then pushed commit Task list (5/5 completed)
|
2 participants
Summary
/guides/proxy/sandboxing, while the per-tool recipes move to a new Sandboxes group under Ecosystem at/sandboxes/*with a short overview. They are integration-shaped, and some may get published packages laternewbadges, and keep old section hashes working via early client redirects on hub pagesAlso
varlock init --agentguidancecollapsedin the Starlight sidebar state hash so default-expanded groups actually stickintegrations/vitesections (vite.config.*, HTML templates, other scripts, type-safety) that Static/dynamic config controls #750 dropped without replacing#plugin-installation,/guides/type-generation/,#regex-literals,#scanning-for-leaked-secrets, and the two#encrypting-the-env-blobanchors (those asides are now real headings)Test plan
/guides/mcp#docs-mcp,/reference/cli-commands#load,/plugins/kubernetes#loading-values) and confirm they redirect to the new pages/guides/dockerredirects to/integrations/docker//guides/sandboxingredirects to/guides/proxy/sandboxing/, and each/guides/sandboxing/<tool>to/sandboxes/<tool>//prompt-builder/, pick a few tiles (incl. monorepo + AI tool + plugin), copy the prompt, and check links resolvebun run --filter @varlock/website build