中国 帮助

文档站维护说明

website/ 下其实有两个独立站点: 官网 文档站(你正在看的这个) 目录 website/site/ website/docs/ 技术 纯静态(生成式 HTML,零依赖) VitePress

文档站维护说明
封面

> 本文整理自平台文档 docs/wujies/1.x/reference/website.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae3282f521f-cover.svg)

website/ 下其实有两个独立站点:

官网文档站(你正在看的这个)
目录website/site/website/docs/
技术纯静态(生成式 HTML,零依赖)VitePress
页面首页 / 功能 / 应用市场 / 快速开始 / 关于九个章节共 55+ 页
产物website/site/docs/website/docs/.vitepress/dist/
依赖无(不需要 npm install)vitepress

「website/site/ 的产物目录也叫 docs/」有点绕,但这是刻意的: 官网构建时会把 VitePress 的产物收进自己的 docs/ 子目录, 于是 website/site/docs/ 就是一个自包含的发布目录 —— 官网在根,文档在 /docs/ 下。

---

官网(website/site/)

为什么是"生成式纯静态"

导航、页脚、应用卡片如果在 5 个 HTML 里各写一遍,改一处要改五处,必然漂移。 所以用 build.mjs 从模板 + 数据渲染出静态 HTML —— 产物仍然是可双击打开的纯静态文件,但维护面只有一份模板。

website/site/
├── build.mjs              构建入口(含本地预览服务器)
├── check-links.mjs        产物站内链接校验
├── src/
│   ├── layout.mjs         <head> + 顶部导航 + 页脚
│   ├── partials.mjs       应用卡片、能力卡、章节标题等复用片段
│   └── pages/             五个页面模板
└── assets/                样式、脚本、logo(构建时原样复制)
cd website/site
node build.mjs           # 构建(会顺带并入文档产物)
node build.mjs --serve   # 构建 + 本地预览(默认 5190)
node check-links.mjs     # 校验站内链接

数据来自哪里

应用名称、版本、菜单数、形态、分类,全部来自 website/docs/data/apps.json —— 由 website/scripts/gen-apps.mjs 扫描各应用 app.json 生成。

要改这些数字,改应用清单,不要改官网。 如果数据文件不存在,构建会直接报错并提示先跑数据生成脚本。

改品牌的地方

改什么改哪
站点名、标语、描述、仓库地址build.mjs 顶部的 SITE 常量
顶部导航项build.mjs 的 NAV 数组
Logoassets/img/logo.svg(favicon 在 src/layout.mjs 里内联)
备案号src/layout.mjs 的页脚(当前是占位符)

SITE.docsUrl 必须以 / 结尾(用于拼接 ${docsUrl}guide/xxx.html), 而 SITE.docsHome 是文档首页的完整文件名。

两者混用会拼出 ./docs/index.htmlguide/... 这种错链接 —— check-links.mjs 就是为了在构建后立刻抓到这类问题而存在的。

---

文档站(website/docs/)

目录结构

website/
├── package.json                 站点自己的依赖(与 plus-ui 相互独立)
├── scripts/
│   ├── gen-apps.mjs             扫描各应用 app.json → 生成首页/生态页用的数据
│   ├── gen-sidebar.mjs          扫描 docs/<章节>/**/*.md → 生成侧边栏数据
│   └── check-site.mjs           校验侧边栏指向、站内链接、首页数据
└── docs/                        ★ VitePress 的 srcDir
    ├── .vitepress/
    │   ├── config.mts           站点配置:导航 / 搜索 / 页脚(侧边栏是下面那份 import 进来的)
    │   ├── sidebar.mjs          构建期生成(scripts/gen-sidebar.mjs),不要手改
    │   └── theme/               ★ 可选:只做配色,删掉站点照常可用
    │       ├── index.ts         extends DefaultTheme,只 import 下面的 CSS
    │       └── custom.css       主题色 / hero / 卡片 / 表格 / 代码块
    ├── index.md                 首页(VitePress **原生** home 布局:hero + features + 正文)
    ├── public/                  静态资源(logo.svg、hero-wujies.svg 等)
    ├── data/apps.json           构建期生成(scripts/gen-apps.mjs),不要手改
    ├── guide/                   开始使用
    ├── architecture/            架构
    ├── plugin-dev/              插件开发
    │   ├── index.md             章节首页
    │   ├── demo.md              跟着 hello 读源码
    │   ├── basics/              基础:不变量、应用清单
    │   ├── backend/             后端工程 + 本地联调
    │   ├── frontend/            前端远程应用
    │   └── advanced/            进阶:菜单、迁移、种子数据、抽模块、贡献指南
    ├── api/                     API 手册(开放接口 / SDK 契约 / 定位器 / 前端运行时)
    ├── package/                 打包与上架
    ├── deploy/                  部署
    ├── ops/                     运维
    ├── ecosystem/               应用生态
    └── reference/               参考

两者不是一回事:

  • website/docs/ 是本站的内容源(在 git 里);
  • 仓库外层的 docs/ 是设计与方案文档(不在任何 git 仓库里)。

本站「设计与决策存档」一节引用的是后者。

本地开发

cd website
npm install
npm run dev          # 开发服务器,默认 5180 端口

其它脚本:

命令作用
npm run gen:apps只重新生成应用数据
npm run gen:sidebar只重新生成侧边栏数据(加页面 / 改目录之后跑它)
npm run check:contrast量 custom.css 里品牌色 / 按钮底色的对比度(品牌色上的白字要 ≥ 4.5:1)
npm run build构建到 docs/.vitepress/dist
npm run preview预览构建产物
npm run clean清掉构建产物

它们来自构建期扫描各插件目录下的 app.json,产物是 docs/data/apps.json。

要改应用的数量、版本、菜单数,请改应用清单,不要改文档。

主题层是可选的(一条硬约定)

docs/.vitepress/theme/ 只提供配色:index.ts 除 import './custom.css' 外什么都不做, 不注册任何组件。原因是一次真实事故 —— 这个目录曾经整个丢失,而当时首页依赖它里面的 <HomePage />,结果是首页白屏(只剩空白,字都没有)。

所以约定是:

* 首页必须是 VitePress 原生 home 布局(frontmatter 的 hero / features + Markdown 正文), 不依赖任何自定义组件;首页正文里的区块只用 Markdown + 原生结构写; * 主题里不要加"首页必须依赖它才能渲染"的组件; * 主题里不要引外部字体 / 图片 / CDN,视觉元素自绘在 `docs

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae3282f521f-guide.svg)

章节导览
THE END

喜欢就支持以下吧

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

回到内容