中国 帮助

文档站维护说明

本站(wujiessite 仓库)是官网 + 文档站,同一个 Next.js 应用、同一套构建: 官网 文档站(你正在看的这个) 位置 app/(home)/ 与 app/team/、app/users/、app

文档站维护说明
封面

> 本文整理自平台文档 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 lintESLint
pnpm types:checknext 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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容