c2cd615824
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.
2.8 KiB
Documentation Instructions
These rules apply to docs/ changes in addition to the root instructions.
Who the docs are for
Two audiences, nothing else. If a page serves neither, it does not belong here.
- People using the app —
start/,desktop/,im/. No prior code knowledge assumed. - People reading the source —
internals/,cli/. Architecture, implementation, contributing.
Internal process artefacts (migration task lists, validation checklists, design proposals, release runbooks) are not documentation. Keep them out of docs/, or fold the durable part into internals/contributing.md.
Structure
Five top-level sections: start/, desktop/, im/, cli/, internals/. Adding a sixth means registering it in the sections array of site/scripts/generate-docs-manifest.mjs.
docs/en/ mirrors the Chinese tree file for file. Keep Chinese pages and their docs/en/ counterparts aligned.
Frontmatter (required on every page)
---
title: 连接模型服务
nav_title: 连接模型 # sidebar label, ≤12 CJK characters
description: 一句话说明这篇讲什么。 # feeds search and SEO meta
order: 2 # position inside the section; index.md uses 0
---
The site renders the first paragraph after the H1 as a lede — write it as a normal paragraph, not a blockquote.
Chinese typography
Put a space between Chinese characters and adjacent Latin letters or digits: 「一枚 6 位码」, 「回填 App ID」. Nothing in the render pipeline inserts it for you, so it has to be in the source. Punctuation needs no space.
Screenshots
Product screenshots live in docs/images/app/ as WebP at 2000px wide, captured from a real build. Never ship a screenshot from an older UI generation; re-capture instead. Redact tokens, QR codes, API keys and paired account names before committing. Cap feature pages at roughly three screenshots.
Step-by-step setup walkthroughs are the exception: docs/im/ embeds console screenshots from docs/images/im/<platform>/ and needs one per step. Judge those by whether a reader could follow along without them.
Routes are file paths
docs/start/install.md publishes to /start/install. Renaming a file changes a public URL, so add the old path to LEGACY_ROUTES in site/src/content/docs.js and to legacyRoutes in site/scripts/prepare-static-output.mjs.
/im/ is linked from inside the desktop app (desktop/src/pages/AdapterSettings.tsx). That route cannot move.
Checks
- Run
bun run check:docswhen selected bybun run check:impact. It installs the isolatedsite/dependency tree, builds the React site, then validates every local link and image. - Release instructions must stay consistent with
scripts/release.ts,.github/workflows/release-desktop.yml, and the versioned release-notes convention.