@model-go/docs-core 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @model-go/docs-core
+
+ModelGo 文档的**单一真源**：文档内容 + 纯渲染器 + 正文样式。
+
+## 为什么存在
+
+文档原来只有 `modelgo-doc-web` 一个消费方，内容和渲染器都长在它的 VitePress 主题里
+（`import.meta.glob('?raw')` 把 markdown 打进浏览器包，运行期在浏览器渲染）。
+现在官网也要读文档（`modelgo.ai/docs`），而 Google 要的是**服务端渲染的真 HTML**——
+如果两个站点各抄一份渲染逻辑，早晚漂移。
+
+所以把「内容 + 渲染器」抽成这个包：内容只有一个真源，渲染只有一个实现，
+两个消费方只是传入不同的挂载前缀：
+
+| 消费方 | 站点 | linkBase | assetBase |
+|--------|------|----------|-----------|
+| `modelgo-doc-web` | `docs.modelgo.com` | `''` | `''` |
+| `modelgo-global-web` | `modelgo.ai/docs` | `/docs`（en）、`/zh/docs`（zh） | `/docs` |
+
+## 用法
+
+```ts
+import { getDocsNav, getDocsPage, getDocSlugs } from '@model-go/docs-core'
+
+const nav = await getDocsNav('en', 'global')
+const page = await getDocsPage('quickstart/overview', 'en', 'global', {
+  linkBase: '/docs',
+  assetBase: '/docs',
+})
+// page.html 是服务端渲染好的正文 HTML，page.toc 是目录
+```
+
+样式：
+
+```css
+@import '@model-go/docs-core/styles/docs-tokens.css';   /* --docs-* ← --mg-*，需先加载 modelgo-design-tokens */
+@import '@model-go/docs-core/styles/docs-content.css';  /* 正文排版 */
+```
+
+图片：`assets/images/**`，消费方自行复制到自己的静态目录（官网复制到 `/docs/images`）。
+
+## 约束
+
+- 渲染器**不得引入任何浏览器 API**（`location` / `navigator` / `storage` / DOM）。
+  站点/语言由调用方显式传入 `profile`、`lang`，包内不做任何运行期探测——
+  这是官网能把它跑在服务端的前提。
+- `tsconfig.json` 的 `lib` 只有 `ES2022`（不含 DOM），用来在编译期卡住上面的约束。
+
+## 发版
+
+```bash
+npm publish             # prepublishOnly 会自动跑：sync:assets → build → 发版门禁
+```
+
+`prepublishOnly` 串了四步，`npm publish` 无论本地发还是 CI 发都必然走到：
+
+1. `sync:assets` —— 把正文实际引用到的图片从 `../../public/images` 同步进 `assets/`
+2. `build` —— `tsc` + 生成 `dist/content.generated.js`
+3. `prepublish-gate` —— 产物完整性（入口字段/pack 清单/CHANGELOG/运行期载荷变化）
+4. `readme-gate` —— 首屏包装。**本包显式 `README_GATE=off`**：`open_source_project_baseline`
+   要求的是「GitHub 开源项目」首屏（banner/立体徽章/双语），而本包是**内部包**——
+   源码在自建 GitLab、消费方只有 ModelGo 自己的两个站点、不做社区推广。
+   逃生舱会打印一行跳过提示，不是静默通过；哪天要对外推广，删掉这个前缀即可。
+
+两个门禁的真源在 `CortexOS/scripts/release-gate/`，`scripts/` 下的是拷贝。
+**改真源，别改拷贝** —— 拷贝漂移会让各仓的拦截口径不一致。
+
+### 图片格式
+
+截图一律用 **WebP**，不用 PNG。2026-09-28 实测：58 张 UI 截图原为 PNG 共 27.6 MB
+（单张最大 2.2 MB），转 WebP q85 后 2.3 MB，**省 91.5%**，PSNR 36–42 dB，
+小字号代码文字仍清晰可读。PNG 存 UI 截图压缩率极低，是纯浪费。
+
+- 新增图片后跑 `python3 ../scripts/optimize-images.py` 转换
+- 正文引用写 `.webp`；`scripts/switch-refs-to-webp.py` 可批量改引用
+- 原始 PNG 保留在 `../../public/images`（已对外发布过的 URL 不能 404），
+  但不会被同步进包 —— 只有正文引用到的文件才进包

package/dist/code-highlight.d.ts

@@ -0,0 +1 @@
+export declare function renderCodeBlock(code: string, lang?: string): string;

package/dist/code-highlight.js

@@ -0,0 +1,50 @@
+const KEYWORDS = new Set([
+    'async',
+    'await',
+    'body',
+    'const',
+    'curl',
+    'fetch',
+    'GET',
+    'headers',
+    'JSON',
+    'method',
+    'POST',
+    'return',
+    'stringify',
+]);
+const LITERALS = new Set(['false', 'null', 'true']);
+const TOKEN_RE = /("[^&]*(?:&(?!quot;)[^&]*)*"|'[^&]*(?:&(?!#39;)[^&]*)*'|\b[A-Za-z_][\w-]*\b|\b\d+(?:\.\d+)?\b|[{}[\]():,])/g;
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+function classNameForToken(token) {
+    if (token.startsWith('&quot;') || token.startsWith('&#39;'))
+        return 'code-string';
+    if (KEYWORDS.has(token))
+        return 'code-keyword';
+    if (LITERALS.has(token))
+        return 'code-literal';
+    if (/^\d/.test(token))
+        return 'code-number';
+    if (/^[{}[\]():,]$/.test(token))
+        return 'code-punctuation';
+    return null;
+}
+export function renderCodeBlock(code, lang = '') {
+    const highlighted = escapeHtml(code).replace(TOKEN_RE, (token) => {
+        const className = classNameForToken(token);
+        return className ? `<span class="${className}">${token}</span>` : token;
+    });
+    const languageClass = lang ? ` language-${escapeHtml(lang.toLowerCase())}` : '';
+    const langLabel = lang ? escapeHtml(lang.toLowerCase()) : '';
+    const langTag = langLabel
+        ? `<span class="code-header-lang">${langLabel}</span>`
+        : '';
+    return `<div class="code-window${languageClass}"><div class="code-header"><span class="code-header-dots"><i></i><i></i><i></i></span>${langTag}<button class="code-copy-btn" type="button" title="Copy" aria-label="Copy code"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button></div><pre class="code-block"><code>${highlighted}</code></pre></div>`;
+}

package/dist/content.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCS_PAGES: Record<string, string>
+export declare const DOCS_METAS: Record<string, unknown>