> 本文整理自平台文档 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 数组 |
| Logo | assets/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)


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