Redesign docs site to match sibling opencdd.github.io design - #22
Merged
Conversation
Replaces Starlight with the design system used by the sibling browser project at https://opencdd.github.io/ - same Tailwind v4 @theme palette (paper, ink, clay, teal, lapis, hex, coral), same prose-opencdd typography, same Header/Footer/BaseLayout/ProseLayout/DocsLayout structure. Adapted for docs-only deployment by dropping the browser-specific CommandPalette, dictionary nav, ThemeToggle, mobile nav, and decorative animations. Design system ported: - src/styles/global.css copied verbatim (780 lines, both light + dark palettes plus manual override) - Header.astro, Footer.astro, Card.astro, SkipToContent.astro ported and slimmed to docs-only scope - BaseLayout, ProseLayout, DocsLayout chained: Base provides Header + Footer + main; Prose adds max-w + prose styling; Docs adds sidebar - cn.ts classname helper - Logo SVGs (light + dark) + favicons + webmanifest in public/ Astro setup migrated: - Dropped @astrojs/starlight + starlight-tailwind + tailwind v3 adapter - Added @astrojs/vue + @astrojs/mdx + @tailwindcss/vite (Tailwind v4) - tsconfig adds ~ / ~/* path alias Content restructured: - src/content.config.ts (Astro 5 glob loader) replaces the Starlight config. Schema mirrors the sibling's docs: title, description, published, updated, order, section, tags - All 10 existing markdown pages get published + section + order - Stripped duplicate body h1 (DocsLayout's header already shows title) - Removed index.mdx (Starlight splash); new pages/index.astro hero 12 pages build cleanly. Inert legacy files (custom.css, old logo.svg) left in place per never-delete-source rule.
Astro 7 (pulled in by the redesign) requires Node >= 22.12.0. The previous pin to Node 20 was set when the docs site ran on Astro 5 via Starlight and worked fine; now it crashes on startup with 'Node.js v20.20.2 is not supported by Astro'. 22 is the current LTS and what the sibling browser project uses.
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
Replaces the Starlight-based docs with the design system used by
the sibling browser site at https://opencdd.github.io/. Same color
palette, typography, and layout — adapted for a docs-only deployment.
Design system ported
src/styles/global.css— the Tailwind v4@themeblock with thefull OpenCDD palette (paper, ink, clay, teal, lapis, hex, coral)
in light + dark + manual override variants. Copied verbatim.
src/components/ui/SkipToContent.astro,Card.astro— direct ports.src/components/layout/Header.astro— simplified (drops commandpalette, dictionary nav, mobile nav, theme toggle). Docs nav: Home,
Docs, GitHub, OpenCDD Browser.
src/components/layout/Footer.astro— simplified footer withProject / Elsewhere nav.
src/layouts/BaseLayout.astro,ProseLayout.astro,DocsLayout.astro— sidebar-aware docs layouts.
src/lib/cn.ts— classname joiner.public/img/opencdd-logo_{light,dark}.svg+ favicons + webmanifest.Astro setup migrated from Starlight → vanilla Astro + Vue + MDX
@astrojs/starlight,@astrojs/starlight-tailwind,@astrojs/tailwind(Tailwind v3 adapter).@astrojs/vue,@astrojs/mdx,@tailwindcss/vite(Tailwind v4via Vite plugin),
vue,tailwindcss@^4.astro.config.mjsmirrors the sibling config:vue() + mdx()integrations,tailwindcss()Vite plugin.tsconfig.jsonadds~/~/*path alias forsrc/.Content collection restructured
src/content.config.ts(Astro 5 path) replacessrc/content/config.ts(Starlight path). Schema:
title,description,published,updated,order,section,tags— matches the sibling's docs schema.published: 2026-07-25section+order. Bodies unchanged except stripping the duplicated# Titleh1 (now provided by DocsLayout's header).index.mdx(Starlight splash page); replaced with customsrc/pages/index.astrohero.New pages
src/pages/index.astro— home page with hero, "What is opencdd?" cards,Ruby code sample, install snippet. Mirrors the sibling's hero styling.
src/pages/docs/index.astro— docs landing page grouping entries bysection with colored Card containers.
src/pages/docs/[...slug].astro— dynamic per-doc route with sidebarnav and "Edit this page on GitHub" link.
Inert legacy files left in place
src/styles/custom.css(Starlight CSS overrides) — kept per the"never delete source" rule; no longer loaded.
src/assets/logo.svg— kept; superseded bypublic/img/.Test plan
npm run build— 12 pages generated cleanlynpm run preview— home, docs index, docs/getting-started/,docs/ontology/ all render with design tokens (paper-50 backgrounds,
ink-900 text, hex-600 accents)