@xcan-cloud/docx

v0.2.3

Published

7 days ago

Self-contained, embeddable documentation site (Next.js 15 + Fumadocs). Mintlify-grade features with Anthropic-style visual identity.

0High
0Medium
0Low

xiaolong.liu666

@xcan-cloud/docx

语言： English · 简体中文（本页）

面向 AngusKit 生态的自包含、可嵌入文档站方案：既可作为独立 Next 应用开发与预览，也可通过 npm 包挂载到任意 Next.js 宿主的子路由。

视觉 — 参考 Claude / Anthropic 类文档站：三栏、暗色优先、紧凑排版、品牌色点缀的衬线标题。
能力 — 对标 Mintlify 级体验：搜索、面向 LLM 的导出、多产品 / 多版本 / 多语言、内嵌 OpenAPI、从宿主注入主题与国际化。
形态 — 开发时在 docx/ 内独立 next dev；发布产物与运行时组件通过 @xcan-cloud/docx 导出，AngusKit 官网在 /[locale]/docs/* 下挂载（见 website/src/app/[locale]/(docs)/）。

状态： P0 就绪（typecheck + vitest + build + dev 冒烟通过）。深度部署与多厂商分析集成属 P1 范畴。

1 · 定位

| | docx | website | | --- | --- | --- | | 技术栈 | Next.js 15 · App Router · Tailwind v4 | Next.js 15 · App Router · Tailwind v4 | | 角色 | 可复用文档 组件库 + 独立作者端应用 | 营销站 + 文档宿主壳 | | 职责 | 多产品/版本/语言路由、MDX、OpenAPI、AI 相关出口 | 对外页面；在 /docs 嵌入 docx | | 受众 | website 或其它 Next 宿主 | 终端用户 |

宿主通过 npm 包 @xcan-cloud/docx（workspace 或已发布版本）集成。

2 · 目录结构

docx/
├── app/                       独立站 App Router（仅自研预览用）
│   ├── layout.tsx             根级 ThemeBridge / LocaleBridge / DocxConfigProvider
│   ├── page.tsx               站点落地页
│   ├── [product]/[version]/[locale]/
│   │   ├── layout.tsx         <DocsLayout sidebar=… />
│   │   ├── [[...slug]]/page.tsx   MDX 渲染（含索引页）
│   │   ├── _render.tsx        内部页面渲染
│   │   ├── _openapi.tsx       frontmatter.openapi 内嵌参考
│   │   └── api-reference/page.tsx  完整 Scalar 参考页
│   ├── api/search|markdown/   搜索与 Markdown 导出
│   ├── llms.txt / llms-full.txt
├── components/                ← 随包发布
├── content/                   本地 MDX 源（不进入 dist）
├── lib/                       ← 随包发布（source.ts 除外）
├── exports/                   对外入口
├── scripts/build-pkg.mjs
├── source.config.ts
└── README.md / README.zh.md

3 · 快速开始（独立开发）

cd AngusKit/docx
nvm use 22                  # Node ≥ 19.9（我们在 v22 上测）
npm install
npm run dev                 # 默认 http://localhost:4202

npm run build
npm run typecheck
npm test
npm run build:pkg           # 打开发布用 dist/

脚手架（scripts/）：

npm run new:product -- crm "客户关系管理" "Customer relationship mgmt" v1
npm run new:version -- ai v3
npm run new:page    -- ai v2 zh guides/quickstart

4 · 编写文档

页面即带 YAML frontmatter 的 MDX：

---
title: Quickstart
description: Spin up your first agent in 5 minutes
order: 10
keywords: [getting-started, agent, install]
openapi: { spec: openapi, operation: createAgent }   # 可选
---

import { Callout, Steps, Step, Card, Cards } from "@xcan-cloud/docx";

多语言：在各 locale 目录下保持相同 slug 镜像即可：

content/ai/v2/
  openapi.zh.yaml
  openapi.en.yaml
  zh/quickstart.mdx
  en/quickstart.mdx

OpenAPI 文件回退顺序：openapi.{locale}.ext → 产品默认语言 → 无语言后缀 openapi.ext。

5 · 发布包

npm run build:pkg 通过 scripts/build-pkg.mjs（esbuild）生成 dist/ ESM 树：保留 "use client"，将 @/ 重写为相对路径，外部化 peer 依赖。

不会打进 dist/ 的模块：lib/source.ts（依赖仅在本仓库构建时存在的 @/.source）。宿主需自建内容管线，将 SidebarNode[] 等传入 <DocsLayout />。

6 · 宿主集成（概要）

安装后在一次包裹文档区的 layout 中引入 @xcan-cloud/docx/styles，用 DocxApp 注入 theme / locale / config，再以 DocsLayout 承载侧栏与正文。完整 TSX 示例见英文 README.md §6。

三个注入点：

主题 — DocxApp.theme / ThemeBridge（HSL 三元组 token，如 accent）。
语言 — LocaleBridge；OpenAPI 文件命名与上文一致。
配置 — DocxConfigProvider / DocxApp.config：端点、功能开关（search、copyAsMarkdown、aiActions、toc、switchers 等）、classNames、AI 外链构造器、Scalar 配置。

样式作用域与 `.docx-root`

发布的 dist/styles.css（即 @xcan-cloud/docx/styles）会把 CSS 变量挂在 :where(.docx-root) 上，并重写 .dark 选择器，以便与宿主 next-themes 在 <html> 上切换的暗色类协同。<DocxApp> 默认渲染 .docx-root 包裹层；独立站通过 unstyledRoot 等内部策略把根上提到 body。

AngusKit 官网参考：website/src/app/[locale]/(docs)/（含 next-themes 与 DocxApp.theme.mode 桥接）。

Next.js 15

包为 ESM + "use client"。Next 15 一般无需 transpilePackages；若宿主仍为 Next 13/14，请在 next.config 中加入 transpilePackages: ["@xcan-cloud/docx"]。

7 · 主题与对比度

设计令牌定义于 lib/theme/tokens.css，并在 lib/theme/tokens.ts 中镜像；tests/lib/theme/contrast.test.ts 对主要 (前景, 背景) 组合做 WCAG AA 校验。

改色流程：同时修改 CSS 与 TS 镜像 → 跑对比度测试 → 修到全绿。

正文默认 14px；MDX 使用 docx-prose 锁定排版与代码块字号。

独立站：主色时间轮换

可选的四套主色（红 → 蓝 → 绿 → 橙）轮换由 lib/theme/primary-rotation.ts 实现；app/layout.tsx 在主题初始化脚本之后注入极小的内联脚本，向 <html> 写入 --docx-accent-light / --docx-accent-dark。tokens.css 将 --color-accent 绑定到上述变量并保留静态 HSL 回退。

| 环境变量 | 含义 | | --- | --- | | NEXT_PUBLIC_DOCX_PRIMARY_ROTATION_DAYS | 每个调色板持续天数（默认 7）。0 / off / false 关闭。 | | NEXT_PUBLIC_DOCX_ACCENT_ROTATION_DAYS | 旧名；仅在新变量未设置时读取。 |

8 · MDX 插件预设

lib/mdx-plugins.ts：remarkPresets（gfm、admonition、steps）、rehypePresets（外链安全）、codeOptions（Shiki）、getDocxMdxOptions（组合 fumadocs 预设）。宿主若在外部编译 MDX（如博客），应复用同一套以保证视觉一致。

9 · AI 友好出口

GET /api/markdown?path=… — 原始 Markdown
GET /llms.txt — llmstxt v1 索引
GET /llms-full.txt — 全文聚合
<CopyAsMarkdown> 内「在 ChatGPT / Claude 中打开」— 可通过 DocxConfig.ai 覆盖 URL 构造

9.1 分析与反馈（宿主适配器）

通过 DocxAnalyticsAdapter 与 DocxFeedbackAdapter 注入；docx 不直接依赖具体厂商 SDK。内置 AnalyticsBoot 在路由变化时发送 docx.page_view。详见英文 README 中的完整示例代码。

9.2 搜索适配器与静态索引

默认 Fuse 实现；宿主可提供静态 JSON 或自定义 DocxSearchAdapter。@xcan-cloud/docx/host-content 中的 writeHostSearchIndex 可在构建期写出索引文件。英文 README §9.2 含完整调用示例。

9.3 博客 / Changelog / RSS

提供 BlogIndex、ChangelogList 及 listHostBlogPosts 等加载器；支持 locale-suffixed 与 locale-flat 两种磁盘布局；buildRssFeed 生成 RSS 2.0。细节与代码块见英文 README §9.3。

10 · 测试

npm test

所有单测集中在 tests/ 下（目录结构与 lib/、components/ 对应）。主要覆盖：messages 深合并、openapi 索引与回退、ThemeBridge、contrast、primary-rotation、sidebar-order、搜索 / 反馈 / feeds 等组件与 host-content 加载器。

11 · 路线图（节选）

✅ P1 — 分析适配器、页脚 prev/next、编辑链接、反馈组件等。
✅ P1.5 — 搜索适配器契约 + 静态索引生成。
✅ P1.6 — 博客 / Changelog 无头组件与 RSS 辅助函数。
P2 — SDK 片段生成、Algolia、可观测性、ISR/Edge 调优等。

由 AngusKit 团队维护。技术细节与长代码示例以 README.md（英文） 为准；本页侧重中文读者快速建立心智模型与查找入口。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xcan-cloud/docx

1 · 定位

2 · 目录结构

3 · 快速开始（独立开发）

4 · 编写文档

5 · 发布包

6 · 宿主集成（概要）

样式作用域与 .docx-root

Next.js 15

7 · 主题与对比度

独立站：主色时间轮换

8 · MDX 插件预设

9 · AI 友好出口

9.1 分析与反馈（宿主适配器）

9.2 搜索适配器与静态索引

9.3 博客 / Changelog / RSS

10 · 测试

11 · 路线图（节选）

样式作用域与 `.docx-root`