mirror of https://github.com/NanmiCoder/cc-haha synced 2026-08-01 16:43:37 +08:00

程序员阿江(Relakkes) c2cd615824 docs: rebuild the documentation site around two readers

The site had drifted from the product. Every screenshot predated the
v0.5.0 UI redesign, the reading experience shipped no search and no
syntax highlighting, and a third of the pages were internal process
artefacts — migration task lists addressed to agentic workers, a
release runbook, a proposal marked "historical".

Reorganise around the only two people who read this: someone getting
the desktop app running for the first time, and someone reading the
source. Five sections replace nine — start / desktop / im / cli /
internals — and the pages that served neither reader are gone.

Site rewrite:

- Palette lifted from the desktop app's 「纸·墨·印」 themes, so the
  site and the product read as one thing. Light mirrors 纯白, dark
  mirrors 墨夜, and dark mode exists at all now.
- Fonts are self-hosted. The old @import from Google Fonts is
  unreachable from mainland China, which left every heading in a
  fallback serif; it also only requested weight 600 while the CSS
  asked for 900, so Latin and CJK in the same heading disagreed.
- Docs were shipped as one 968KB manifest downloaded on every page
  view. Split into a 32KB index plus one lazily imported chunk per
  page; the entry bundle is now 101KB gzipped.
- Add search, syntax highlighting, per-route meta with canonical and
  hreflang, a sitemap, and an error boundary. Replace the 44vh
  mobile sidebar with a drawer.
- Image dimensions are read at build time and written into the tag,
  so lazy images reserve their space instead of collapsing.

Screenshots are recaptured from a real v0.5.0 build against a clean
demo project, with tokens, QR codes and paired accounts redacted.
The previous set is deleted rather than kept alongside.

Routes follow file paths, so the restructure would have broken every
inbound link; 37 old paths redirect, in both languages. The PR policy
gate and CODEOWNERS also hardcoded docs/guide/contributing.md.

Verified: check:docs 78 pages / 323 links / 0 problems, check:policy
127 pass. Walked every route at 1440 and 390 in both themes for
overflow, contrast, keyboard reachability and focus management.

2026-07-27 17:32:41 +08:00

3.5 KiB

Raw Blame History

React Site Instructions

These rules apply to the public landing page and documentation experience under site/.

Contracts that must not break

Keep the site independently installable with npm ci and buildable with npm run build.
Keep npm run check deterministic, offline, and responsible for site-specific validation beyond compilation.
Preserve the GitHub Pages custom-domain contract; production assets and routes must work from the root of claudecode-haha.relakkesyang.org. scripts/prepare-static-output.mjs hard-fails when the CNAME drifts.
Treat files under docs/ as the source of truth for long-form Chinese and English documentation. Keep paired public routes aligned when both languages exist.
Do not copy private user state, credentials, local filesystem paths, or unredacted product screenshots into the site.
Run bun run check:docs after site or docs changes and include desktop plus narrow-mobile browser evidence for user-visible layout changes.

How content reaches the site

scripts/generate-docs-manifest.mjs scans docs/, then emits three things into src/generated/ (gitignored):

docs-index.js — the eager index: route, section, title, nav_title, description, order. Keep it small; it ships on every page.
content/<id>.js — one module per document holding the markdown body (frontmatter already stripped). docsContent maps a route to a dynamic import, so opening one page never downloads the rest.
search-index.js — lazily imported by the search dialog only.

Routes come from file paths (docs/start/install.md → /start/install). Renaming a file renames its URL, so add the old path to both LEGACY_ROUTES in src/content/docs.js and legacyRoutes in scripts/prepare-static-output.mjs.

Sidebar grouping comes from the sections array in the generator — register any new top-level docs/ directory there or it sorts last with a bare directory name. Order inside a group comes from each document's order frontmatter.

Design system

src/styles/base.css holds every token. The palette is lifted from the desktop app's 「纸·墨·印」 themes — light mirrors 纯白, dark mirrors 墨夜 — so the site and the app read as one product. Rules:

Use tokens (--surface-*, --text-*, --border*, --brand*, --sp-*, --fs-*, --r-*) rather than literal values. A raw hex in a component is a bug.
The primary button is ink (--ink), turning terracotta (--brand) on hover. It is not brand-coloured at rest.
Depth comes from 1px borders and surface layering, not heavy shadows.
Both themes must work. data-theme on <html> is set by the bootstrap script in index.html before first paint.
Breakpoints are 1180 / 900 / 620 across both stylesheets. Do not introduce a fourth.

Mermaid

````mermaid fences render as diagrams. Nothing under docs/ currently uses one — the two pages that did were deleted in the July 2026 restructure — so the dependency and its .doc-mermaid styles sit unused, lazily loaded and costing readers nothing. Keep them: internals/ is exactly where a diagram would earn its place, and the mermaid theme is already wired to the site tokens.

Fonts

Self-hosted in public/fonts/, copied from desktop/public/fonts/. Never add a Google Fonts @import or <link> — it is unreachable from mainland China and would leave every heading in a fallback serif. Only the latin subsets are hosted; Chinese glyphs fall through to the platform font on purpose, exactly as the desktop app does.

3.5 KiB Raw Blame History