> 本文整理自平台文档 docs/wujies/5.x/platform/reference/website.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f4ca233be03e-cover.svg)
本站(wujies-site 仓库)是官网 + 文档站,同一个 Next.js 应用、同一套构建:
| 官网 | 文档站(你正在看的这个) | |
|---|---|---|
| 位置 | app/(home)/ 与 app/team/、app/users/、app/timeline/、app/sponsor/(另有一份 noindex 的固定样例页) | app/docs/ + 内容源 content/docs/ |
| 技术 | Next.js 16 静态导出 + Fumadocs 16 + Tailwind CSS 4 | 同一套(文档页由 Fumadocs 渲染 MDX) |
| 数据 | data/*.json(成员、赞助、时间线)与构建期统计 | 每篇 .mdx 自己 + 同目录 meta.json |
| 产物 | out/(纯静态文件) | out/docs/** |
没有第二个站点、也没有构建期的文档汇聚步骤:早期那套「从各项目仓库的 docs/ 拉取」 的注册表还留在 lib/docs-sections.ts(repo / ref 字段),但 wujies 分区两个版本的 repo 都是空串 —— 不生成「在 Gitee/GitHub 编辑」链接,也不会真的去拉。 scripts/gen-docs-sources.mjs 会把空 repo 的条目过滤掉,当前输出为空。
---
目录结构
wujies-site/
├── app/ 路由:(home) 官网首页 · docs 文档 · blog · demo
│ ├── docs/[[...slug]]/ 文档页渲染(MDX、TOC、编辑链接按分区映射)
│ ├── api/search/ 静态搜索(构建期预生成 Orama 索引)
│ ├── og/docs/[...slug]/ 构建期预渲染各文档页的 OG 图片
│ ├── llms.txt · llms-full.txt · llms.mdx/ 给 AI 工具检索的纯文本文档
│ └── robots.ts · sitemap.ts SEO Metadata Routes
├── content/docs/wujies/ ★ 文档内容源(5.x 当前版本 / 1.x 只读存档)
│ └── <版本>/…/meta.json 导航:每个目录一份,`pages` 数组决定侧边栏顺序
├── components/ MDX 与官网共用组件(mdx.tsx 的 getMDXComponents 是注册入口)
├── lib/ source.ts(数据源)· docs-sections.ts(分区与版本)·
│ layout.shared.tsx(导航)· shared.ts(站点常量)·
│ timeline.ts / users.ts / team.ts / sponsors.ts(data 的读取层)
├── data/ 官网用的 JSON 数据(成员、赞助者、时间线、用户)
├── scripts/ gen-docs-sources · gen-legacy-doc-redirects ·
│ check-internal-links · add-utf8-bom · preview
├── public/ 静态资源(logo、图片)
├── next.config.mjs output: 'export' + images.unoptimized
├── source.config.ts fumadocs-mdx 配置
└── out/ 构建产物(gitignore)
三个不要顺手改的地方:content/docs/wujies/1.x/ 是只读存档; 5.x/ruoyi-vue-plus/(48 篇)与 5.x/plus-ui/(14 篇)是上游文档镜像, 目录名就是 URL 段,与本项目无关;.github/workflows/ 是上游模板遗留,见「部署」。
---
本地开发
pnpm install # Node >= 22.18,pnpm >= 10(版本经 pnpm-workspace.yaml 的 catalog: 管理)
pnpm dev # 开发服务器 http://localhost:3000,直接渲染仓库内的 content/docs
文档不需要任何前置汇聚,pnpm dev 起来就是真实内容。其它脚本:
| 命令 | 作用 |
|---|---|
pnpm build | 静态导出到 out/(顺带生成旧链接重定向与 UTF-8 BOM) |
pnpm lint | ESLint |
pnpm types:check | next typegen + tsc --noEmit |
pnpm ui:check | 检查本次构建产物的设计契约(tests/*.test.mjs) |
pnpm links:check | 按浏览器 URL 语义解析 out/**/*.html,校验站内路由与锚点 |
pnpm preview | 本地预览 out/ |
> 本机没有外网时 pnpm build 会失败:个别文档页嵌了 img.shields.io 徽章, > fumadocs 在构建期抓取外链图片。此时报错属环境问题,不是文档写坏。
---
版本与导航
URL 与目录一一对应:content/docs/wujies/<版本>/ → /docs/wujies/<版本>/。 版本段走 Fumadocs 的 Root Type(lib/source.ts 把版本目录标成 root: "version"), Docs 布局在侧栏渲染版本下拉,切换时投影到对侧同路径页,缺页则回版本入口。
- 版本 key(
5.x/1.x)一旦上线就是 URL,不要改名;显示名由lib/docs-sections.ts的title决定; - 新增版本要在
lib/docs-sections.ts注册一条,并同步分区meta.json的pages与该版本目录下的 - 页面顺序与分组由每层目录的
meta.json(pages/title/icon)决定,改目录或改名要一并改它。
---
写文档的约定
### frontmatter
每个 .mdx 必须有 title 与 description(后者进 SEO、搜索摘要、OG 图片与 llms.txt):
---
title: 页面标题
description: 一到两句话,说明本页解决什么问题
---
### 链接
站内链接用从站点根算起的绝对路径(/docs/wujies/5.x/platform/architecture/data-model), 不要用相对路径,也不要带 .mdx 后缀;锚点写 #小节。 pnpm links:check 会抓反斜杠 URL、目录假页面和缺失的 fragment。
### 组件与风格
- 简体中文,技术术语保留英文;代码块标语言,命令给可直接复制的完整形式;
- 善用 Fumadocs 组件:
<Cards>/<Card>做导航、<Callout>(或> [!NOTE])做提示、 - 样式一律用 Tailwind 工具类与 Fumadocs 主题变量(
fd-*),不写内联样式; - 版本相关表述要标适用版本(如「自 5.6.2 起」「1.x 仅」)。
### 内容以代码为准
写之前先核代码,别把记忆当事实:路径、模块名、表名、接口、数量都要能在 wujies-platform/ 或对应应用仓库里指认出来。发现页面写错了就直接改这一页 —— 本站的 content/docs/ 就是事实源,不存在「先去项目仓库改 docs 再同步过来」这一步。
---
写文档时不要贴出任何真实凭据与内网信息:
- 服务器地址 / IP、站点根目录路径;
- 数据库、Redis、RabbitMQ 的连接信息与密码;
- Sa-Token 的 JWT 密钥、签名与加解密公私钥的实际值(写占位符即可);
VITE_APP_BASE_API之类的线上地址、任何 token 值。
需要提到形态时写占位符(<库名> / <token>)并加一句「此处为真实凭据,请替
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f4ca233be03e-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。