Skip to content

Commit 00b70fd

Browse files
hyt1004hyt1004
authored
Merge pull request #1 from hyt1004/main
文档项目+github page部署
2 parents 9dba935 + 28d47fc commit 00b70fd

File tree

131 files changed

+4282
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

131 files changed

+4282
-0
lines changed

‎.github/workflows/deploy.yml

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
2+
#
3+
name: Deploy VitePress site to Pages
4+
5+
on:
6+
# 在针对 `main` 分支的推送上运行。如果你
7+
# 使用 `master` 分支作为默认分支，请将其更改为 `master`
8+
push:
9+
branches: [main]
10+
11+
# 允许你从 Actions 选项卡手动运行此工作流程
12+
workflow_dispatch:
13+
14+
# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
21+
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
22+
concurrency:
23+
group: pages
24+
cancel-in-progress: false
25+
26+
jobs:
27+
# 构建工作
28+
build:
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: Checkout
32+
uses: actions/checkout@v4
33+
with:
34+
fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
35+
# - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
36+
# - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
37+
- name: Setup Node
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: 20
41+
cache: npm # 或 pnpm / yarn
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v4
44+
- name: Install dependencies
45+
run: npm ci # 或 pnpm install / yarn install / bun install
46+
- name: Build with VitePress
47+
run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
path: docs/.vitepress/dist
52+
53+
# 部署工作
54+
deploy:
55+
environment:
56+
name: github-pages
57+
url: ${{ steps.deployment.outputs.page_url }}
58+
needs: build
59+
runs-on: ubuntu-latest
60+
name: Deploy
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
node_modules/
2+
yarn.lock
3+
.DS_Store
4+
# local dist
5+
/dist
6+
7+
docs/.vitepress/cache/
8+
docs/.vitepress/dist/
9+
10+
test/

‎README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Xrobot-docs
2+
3+
## 安装
4+
5+
``` shell
6+
npm install
7+
```
8+
9+
## 调试
10+
11+
```shell
12+
npm run docs:dev
13+
```
14+
浏览器打开 http://localhost:5173
15+
16+
## 部署
17+
18+
```shell
19+
npm run docs:build
20+
```
21+
22+
本地预览，执行下列命令后，生成一个本地静态 Web 服务 http://localhost:4173，该服务以 .vitepress/dist 作为源文件
23+
```shell
24+
npm run docs:preview
25+
```
26+

‎docs/.vitepress/config.mts

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import { defineConfig } from "vitepress";
2+
import { ChapterItems, Chapters } from "./theme/constrants/route";
3+
import autoH1 from "./plugins/autoH1";
4+
5+
// https://vitepress.dev/reference/site-config
6+
export default defineConfig({
7+
title: "灵矽文档中心",
8+
description: "A 灵矽 Documentation Project",
9+
lastUpdated: true,
10+
cleanUrls: true,
11+
base: "/Xrobot-docs/",
12+
locales: {
13+
root: {
14+
label: "简体中文",
15+
lang: "cn",
16+
},
17+
// en: {
18+
// label: "English",
19+
// lang: "en",
20+
// },
21+
},
22+
themeConfig: {
23+
// https://vitepress.dev/reference/default-theme-config
24+
outline: [2, 4],
25+
nav: [
26+
{ text: "主页", link: "/" },
27+
{ text: "设备操作指南", link: Chapters.xrobot_device },
28+
{ text: "API参考", link: Chapters.xrobot_api },
29+
{ text: "FAQ", link: Chapters.xrobot_faq },
30+
],
31+
sidebar: {
32+
"/": [
33+
{
34+
text: "Examples",
35+
items: [
36+
{ text: "Markdown Examples", link: "/markdown-examples" },
37+
{ text: "Runtime API Examples", link: "/api-examples" },
38+
],
39+
},
40+
],
41+
...ChapterItems,
42+
},
43+
socialLinks: [
44+
{
45+
icon: "github",
46+
link: "https://github.com/qiniu/Xrobot-docs",
47+
},
48+
],
49+
},
50+
markdown: {
51+
toc: {
52+
level: [1, 2, 3, 4],
53+
},
54+
config: (md) => {
55+
md.use(autoH1);
56+
},
57+
},
58+
});

‎docs/.vitepress/plugins/autoH1.js

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
export default (md) => {
2+
const hasH1 = (content) => /^\s*#\s+.+/m.test(content);
3+
4+
md.core.ruler.before("normalize", "auto_add_h1", (state) => {
5+
const { frontmatter } = state.env;
6+
const src = state.src;
7+
if (frontmatter?.title && !hasH1(src)) {
8+
state.src = `# ${frontmatter.title}\n\n` + src;
9+
}
10+
return false;
11+
});
12+
};

‎docs/.vitepress/theme/components/ChapterContents.vue

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<script setup lang="ts">
2+
import {
3+
ChapterItems,
4+
Chapters,
5+
isChapter,
6+
} from "../../../.vitepress/theme/constrants/route";
7+
8+
const { chapter: chapter_root, root = true } = defineProps<{
9+
// 参数chapter应该是如 Chapter.xrobot_device这样的
10+
chapter: Chapters;
11+
// root用于控制递归生成目录
12+
root?: boolean;
13+
}>();
14+
15+
// console.log("contents");
16+
let chapter_name: string[] = [];
17+
let tocs: { link: string; text: string }[][] = [];
18+
19+
// console.log(chapter_root);
20+
21+
ChapterItems[chapter_root]?.forEach((subchapter) => {
22+
const t = subchapter.items?.filter((item) => {
23+
return item.link !== chapter_root && !item.goback;
24+
});
25+
if (t) {
26+
tocs.push(t);
27+
chapter_name.push(subchapter.text);
28+
}
29+
});
30+
31+
// console.log("chapter_name:", chapter_name);
32+
// console.log("tocs:", tocs);
33+
</script>
34+
35+
<template>
36+
<h1 v-if="root">目录</h1>
37+
<div v-for="(subchapter, index) in tocs">
38+
<h2>{{ chapter_name[index] }}</h2>
39+
<ol>
40+
<li v-for="(item, index2) in subchapter" :key="item.link">
41+
<ol v-if="isChapter(item.link)">
42+
<ChapterContents
43+
:root="false"
44+
:chapter="item.link as Chapters"
45+
></ChapterContents>
46+
</ol>
47+
<a v-else :href="item.link">{{ item.text }}</a>
48+
</li>
49+
</ol>
50+
</div>
51+
</template>

‎docs/.vitepress/theme/constrants/route.ts

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
export type ChapterItem = {
2+
// 标题
3+
text: string;
4+
// 链接
5+
link: string;
6+
// 初始时是否折叠, 如果未指定，侧边栏组不可折叠
7+
collapsed?: boolean;
8+
// 子项，元素顺序影响页面、章节顺序
9+
items?: ChapterItem[];
10+
// 返回上级章节
11+
goback?: boolean;
12+
};
13+
14+
// 章节路由，注意，首尾都要有 `/`
15+
// 不在其中的章节不会正确生成目录
16+
export enum Chapters {
17+
// xrobot 分章
18+
xrobot = "/xrobot/",
19+
xrobot_device = "/xrobot/device/",
20+
xrobot_api = "/xrobot/api/",
21+
xrobot_faq = "/xrobot/faq/",
22+
xrobot_guide = "/xrobot/guide",
23+
xrobot_guide_mp = "/xrobot/guide/mini-program",
24+
}
25+
26+
// 判断一个link 字符串是否是章节link
27+
export function isChapter<T extends Record<string, string>>(
28+
link: string
29+
): link is T[keyof T] {
30+
return Object.values(Chapters).includes(link as Chapters);
31+
}
32+
33+
// 给 ChapterItem 的 link 字段追加当前章节的 link 前缀
34+
function apply_prefix(item: ChapterItem, prefix: Chapters) {
35+
if (item?.link.startsWith("/") && prefix.endsWith("/")) {
36+
return { ...item, link: prefix.slice(0, -1) + item.link };
37+
} else if (!item.link.startsWith("/") && !prefix.endsWith("/")) {
38+
return { ...item, link: prefix + "/" + item.link };
39+
}
40+
return { ...item, link: prefix + item.link };
41+
}
42+
43+
const items_xrobot_api = [
44+
{
45+
text: "API参考",
46+
items: [
47+
{ text: "用户API", link: "user" },
48+
{ text: "智能体API", link: "agent" },
49+
{ text: "设备API", link: "device" },
50+
{ text: "音色克隆API", link: "voice-clone" },
51+
].map((item) => apply_prefix(item, Chapters.xrobot_api)),
52+
collapsed: false,
53+
link: Chapters.xrobot_api,
54+
},
55+
];
56+
57+
const items_xrobot_device = [
58+
{
59+
text: "设备使用",
60+
items: [
61+
{ text: "设备使用指南", link: "device-intro" },
62+
{ text: "设备绑定", link: "device-bind" },
63+
{ text: "设备服务通信协议", link: "device-protocol" },
64+
{ text: "智能体连接指南", link: "device-connection" },
65+
].map((item) => apply_prefix(item, Chapters.xrobot_device)),
66+
link: Chapters.xrobot_device,
67+
collapsed: true,
68+
},
69+
// 子章节
70+
];
71+
72+
const items_xrobot_faq = [
73+
{
74+
text: "常见问题",
75+
items: [{ text: "FAQ", link: "faq" }].map((item) =>
76+
apply_prefix(item, Chapters.xrobot_faq)
77+
),
78+
link: Chapters.xrobot_faq,
79+
// collapsed: false,
80+
},
81+
// 子章节
82+
];
83+
84+
const items_xrobot_guide_mp = [
85+
{
86+
text: "微信小程序",
87+
link: Chapters.xrobot_guide_mp,
88+
collapsed: true,
89+
items: [
90+
{ text: "智能体管理", link: "agent-management" },
91+
{ text: "角色配置", link: "role-config" },
92+
{ text: "设备管理", link: "device-management" },
93+
{ text: "设备配网", link: "device-net-config" },
94+
].map((item) => apply_prefix(item, Chapters.xrobot_guide_mp)),
95+
},
96+
];
97+
98+
const items_xrobot_guide = [
99+
{
100+
text: "操作指南",
101+
link: Chapters.xrobot_guide,
102+
collapsed: false,
103+
items: [...items_xrobot_guide_mp, ...items_xrobot_device],
104+
},
105+
];
106+
107+
// xrobot章节整体
108+
const items_xrobot = [
109+
{
110+
text: "",
111+
items: [
112+
...items_xrobot_guide,
113+
...items_xrobot_api,
114+
// ...items_xrobot_device,
115+
...items_xrobot_faq,
116+
],
117+
link: Chapters.xrobot,
118+
// collapsed: false,
119+
},
120+
];
121+
122+
function gobackItem(chapter: Chapters) {
123+
return {
124+
text: "返回上级",
125+
link: chapter,
126+
goback: true,
127+
};
128+
}
129+
130+
// todo: 把子章节从ChapterItems中抽离出来
131+
export const ChapterItems: Record<Chapters, ChapterItem[]> = {
132+
[Chapters.xrobot]: items_xrobot,
133+
[Chapters.xrobot_device]: [
134+
gobackItem(Chapters.xrobot),
135+
...items_xrobot_device,
136+
],
137+
[Chapters.xrobot_api]: [gobackItem(Chapters.xrobot), ...items_xrobot_api],
138+
[Chapters.xrobot_faq]: [gobackItem(Chapters.xrobot), ...items_xrobot_faq],
139+
[Chapters.xrobot_guide]: [gobackItem(Chapters.xrobot), ...items_xrobot_guide],
140+
[Chapters.xrobot_guide_mp]: [
141+
gobackItem(Chapters.xrobot_guide),
142+
...items_xrobot_guide_mp,
143+
],
144+
};

0 commit comments

Comments
 (0)