Chore: vocs v2 migration#519
Open
scode2277 wants to merge 13 commits into
Open
Conversation
… remove dead code - Relocated components/certified-protocols/ to components/cert/certified-protocols/ since the component is cert-family and css - Deleted the unused withTagFiltering HOC (tsx + css).
Vocs 2.0 / Waku require the package to be ESM. Without "type": "module", Waku's static generation crashes - Add "type": "module" to package.json. - Rename the CommonJS build scripts to .cjs (they use require/module.exports) - Remove the mermaid-wrapper script invocation from docs:dev/docs:build and its script entry; native mermaid support lands in a later commit.
- Bump vocs 1.4.1 -> 2.0.10 (devDependency). - Add waku 1.0.0-beta.1. vocs 2.0 declares waku as an optional peer, so pnpm does not install it, but vocs imports it unconditionally and crashes without it
- vocs 2.0 only discovers vocs.config.{ts,js,mjs,mts}; a .tsx config is silently ignored.
- Drop the vite.define __IS_MAIN_BRANCH__ block
- Add docs/pages/_layout.tsx (global layout, wraps every page in TagProvider)
- _slots.tsx (Footer + SidebarHeader slots)
- new _root.css for global styles
- Waku forbids a file and folder sharing a path, so had to move the four control-domains landing pages X.mdx -> X/overview.mdx
The tag filter and its context are now set up once globally (in the page layout and sidebar slot), so every page no longer needs to wrap itself in <TagProvider>/<TagFilter />. This updates ~299 pages to drop those wrappers while keeping the tag list, attribution, and contribute footer. The page template is updated to match.
vocs 2.0 renders pages as server components by default, so anything using hooks, context, event handlers, or browser APIs needs a "use client" marker, and a few components needed other adjustments to render correctly.
vocs 2.0 serves static files from the root public/ directory, not docs/public/, so anything fetched at /foo must live there. This fixes the certs Export and the Print button. - Update .gitignore for the new printable path, and ignore Waku's generated docs/pages.gen.ts route types.
vocs 2.0 renders mermaid code blocks natively, so the old workaround is gone. vocs 1.x couldn't parse them, so there was a custom MermaidRenderer component plus a build step that rewrote raw blocks into <MermaidRenderer>.
Rework the sidebar tag filter for vocs 2.0's DOM and slot system. - Remap the sidebar control logic to vocs 2.0's data attributes - Move the filter into the SidebarHeader slot: drop the old fixed positioning - Fix section mapping in tags-fetcher: key each section on the folder that directly contains its pages
Theming: - Replace .dark / :root:not(.dark) and @media (prefers-color-scheme) with [data-vocs-theme]-driven selectors across the component stylesheets - Delete the now-unused docs/footer.tsx. - Attack-surface and governance: define their theme tokens locally on their root elements instead of borrowing from cert's control.css CI / workflows: - preview-build.yml: upload dist/public instead of docs/dist - vocs-config-reminder.yml: reference vocs.config.ts instead of vocs.config.tsx.
…t-install to separate PRs
scode2277
added
local setup
frameworks-volunteer
approved these changes
Jun 15, 2026
frameworks-volunteer
left a comment
frameworks-volunteer
left a comment
Collaborator
There was a problem hiding this comment.
Model: z-ai/glm-5.1 Reasoning: medium Provider: openrouter
Review: Chore: vocs v2 migration
Reviewed all non-page infrastructure files (config, components, utils, workflows, CSS) and spot-checked MDX pages.
Security: No issues found
- No hardcoded secrets, tokens, or API keys
- No injection vectors -- querySelector selectors use vocs data attributes, not user input
- DevOnly.tsx:
process.env.CF_PAGES_BRANCHis equivalent to the old__IS_MAIN_BRANCH__vite define (both resolved at build time on CF Pages). No exposure of env vars to client bundles sincerenderStrategy: 'full-static'. - Dependencies: vocs 2.0.10 + waku 1.0.0-beta.1 are the expected upgrade path.
QA: Looks good, with observations
Correctness:
extractUrlSegmentin tags-fetcher.cjs now returnsparts[parts.length - 2]instead ofparts[0], giving nested sections their own identity instead of collapsing onto the parent. Thefetched-tags.jsondiff confirms mappings were regenerated consistently (e.g., "Isolation and Sandboxing" -> "isolation" instead of "devsecops"). This aligns with vocs 2.0 sidebar structure.loadSidebarConfigin generate-folder-indexes.cjs now strips ALL import lines (/(?:import[^\n]*\n)+/) instead of just the first -- correct since vocs.config.ts now has two imports.
CSS / Theming:
- Dark mode selectors consistently migrated:
.dark/:root:not(.dark)->[data-vocs-theme='dark']/:not([data-vocs-theme='dark']). - vocs CSS class names replaced with data-attribute selectors. Clean and consistent.
- CSS custom properties used for theme tokens in GovernanceSDLC.css and ChecklistItem.css (replacing
var(--vocs-color_background)). Good approach.
Components:
"use client"directives added to all interactive components. Correct for RSC boundaries.react-router-domLink -> vocs Link migration is consistent.toprop type casting (as ComponentProps<typeof Link>["to"]) in AttackSurfaceDashboard and GovernanceSDLCPipeline is pragmatic; not ideal but the vocs Link type differs from react-router-dom.- AttackSurfaceDashboard:
round2helper for SSR coord rounding prevents hydration mismatches. Reasonable. - GovernanceSDLCPipeline:
Link-><a>for the "Jump to section" anchor is correct (same-page hash links do not need client-side routing).
MDX pages (~300):
- Mechanical removal of
TagProvider/TagFilterwrappers and imports, now provided globally by_layout.tsx+_slots.tsx. Spot-checked several -- all consistent. - Route-collision fix:
opsec/control-domainssubpages renamed fromX.mdxtoX/overview.mdxwith matching link updates. Correct.
Follow-ups acknowledged:
- Searchbar indexing dropped from postdocs:build (separate PR needed). Acceptable.
- just-install in ignoredBuiltDependencies (CI 403 workaround, separate PR). Acceptable.
- CF Pages build-output dir change is external (dashboard config, not repo). Noted in PR body.
CI: lint and sidebar-reminder pass. CF Pages deploy failure is expected (output path config change needed externally, not in this PR).
No blocking issues. Approving.
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
2 participants
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.
vocs 2.0 is a ground-up rewrite on Waku (React Server Components) + Vite 8, so this spans config, routing, components, CSS, build scripts, and CI. pnpm docs:build passes in test environment. Here it doesn't because we need to update the outputs path on CF dashboard (see
Follow-upssection)How to review
Go commit by commit (13 themed commits). Each commit is one coherent step (ESM switch, deps bump, config + routing, RSC boundaries, native mermaid, theming, etc.), so the diffs read top to bottom.
Why one PR
Every change here is required for a green build. Splitting them would leave the site un-buildable at each step, so they ship together.
What changed, by area
Root (vocs.config.ts, package.json, pnpm-lock.yaml, .gitignore)
docs/pages/ (~300 files)
<TagProvider>) for the whole site, instead of each MDX page wrapping itself.<TagProvider>/<TagFilter />removed from ~299 pages (now provided globally by the layout + slot above); TagList, AttributionList, and ContributeFooter kept.docs/ (top level)
components/
utils/
.github/workflows/
Follow-ups