Skip to content

Commit be633b0

Browse files
XuZhang99XuZhang99
authored
docs: add new docs. (#1935)
1 parent fd736c6 commit be633b0

185 files changed

Lines changed: 31183 additions & 0 deletions

File tree

Some content is hidden

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

‎.github/workflows/build_docs.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Build Docs
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/build_docs.yaml'
10+
push:
11+
branches:
12+
- main
13+
paths:
14+
- 'docs/**'
15+
- '.github/workflows/build_docs.yaml'
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
defaults:
21+
run:
22+
working-directory: docs
23+
steps:
24+
- uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
- name: Use Node.js 22
28+
uses: actions/setup-node@v4
29+
with:
30+
node-version: 22
31+
cache: npm
32+
cache-dependency-path: docs/package-lock.json
33+
- run: npm ci
34+
- run: npm run build
35+
36+
check:
37+
runs-on: ubuntu-latest
38+
defaults:
39+
run:
40+
working-directory: docs
41+
steps:
42+
- uses: actions/checkout@v4
43+
- name: Use Node.js 22
44+
uses: actions/setup-node@v4
45+
with:
46+
node-version: 22
47+
cache: npm
48+
cache-dependency-path: docs/package-lock.json
49+
- run: npm ci
50+
- run: npm run check

‎.github/workflows/deploy_docs.yaml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/deploy_docs.yaml'
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: pages
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
defaults:
24+
run:
25+
working-directory: docs
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
with:
30+
fetch-depth: 0
31+
32+
- name: Setup Node.js
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version: 22
36+
cache: npm
37+
cache-dependency-path: docs/package-lock.json
38+
39+
- name: Install dependencies
40+
run: npm ci
41+
42+
- name: Build
43+
run: npm run build
44+
45+
- name: Upload Pages artifact
46+
uses: actions/upload-pages-artifact@v3
47+
with:
48+
path: ./docs/dist
49+
50+
deploy:
51+
needs: build
52+
runs-on: ubuntu-latest
53+
environment:
54+
name: github-pages
55+
url: ${{ steps.deployment.outputs.page_url }}
56+
steps:
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

‎docs/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
# logs
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
pnpm-debug.log*
14+
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store
22+
23+
# vscode
24+
.vscode/

‎docs/README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# xLLM Documentation
2+
3+
[English](./README.md) | [简体中文](./README.zh-CN.md)
4+
5+
This repository contains the Astro + Starlight documentation site for
6+
[xLLM](https://github.com/xLLM-AI/xllm), an LLM inference framework for
7+
high-performance serving on domestic AI accelerators.
8+
9+
The site is built with Starlight and `starlight-theme-rapide`. It includes a
10+
custom header, bilingual navigation, and a page-level `Copy page` action for
11+
copying documentation content as Markdown.
12+
13+
## Documentation Structure
14+
15+
The documentation is maintained in two parallel language trees:
16+
17+
- English: `src/content/docs/en`
18+
- Simplified Chinese: `src/content/docs/zh`
19+
20+
The root path redirects to the English documentation:
21+
22+
- `/` redirects to `/en/`
23+
- `/en/` serves the English documentation
24+
- `/zh/` serves the Simplified Chinese documentation
25+
26+
When adding or moving pages, keep matching relative paths in both language
27+
trees so Starlight can switch between languages for the same topic.
28+
29+
## Project Layout
30+
31+
```text
32+
.
33+
├── astro.config.mjs # Starlight, locale, sidebar, and component config
34+
├── package.json # npm scripts and dependencies
35+
├── src/
36+
│ ├── assets/ # Site-level assets such as the logo
37+
│ ├── components/ # Starlight component overrides
38+
│ ├── content/
39+
│ │ └── docs/
40+
│ │ ├── en/ # English documentation
41+
│ │ ├── zh/ # Simplified Chinese documentation
42+
│ │ └── assets/ # Documentation images and diagrams
43+
│ ├── pages/index.astro # Redirect from / to /en/
44+
│ └── styles/theme.css # Project theme customizations
45+
└── public/ # Static public assets
46+
```
47+
48+
## Local Development
49+
50+
Install dependencies:
51+
52+
```sh
53+
npm install
54+
```
55+
56+
Start the local development server:
57+
58+
```sh
59+
npm run dev
60+
```
61+
62+
Build the production site:
63+
64+
```sh
65+
npm run build
66+
```
67+
68+
Preview the production build:
69+
70+
```sh
71+
npm run preview
72+
```
73+
74+
## Editing Documentation
75+
76+
- Put user-facing content under `src/content/docs/en` and
77+
`src/content/docs/zh`.
78+
- Keep English and Chinese files aligned by path when a page exists in both
79+
languages.
80+
- Store shared documentation images in `src/content/docs/assets`.
81+
- Update the `sidebar` section in `astro.config.mjs` when adding new sections
82+
that should appear in navigation.
83+
- Run `npm run build` before submitting changes to catch broken routes,
84+
frontmatter errors, and Starlight content issues.
85+
86+
## Related Repository
87+
88+
- xLLM source code: <https://github.com/xLLM-AI/xllm>

‎docs/README_zh.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# xLLM 文档站
2+
3+
[English](./README.md) | [简体中文](./README.zh-CN.md)
4+
5+
本仓库是 [xLLM](https://github.com/xLLM-AI/xllm) 的 Astro + Starlight
6+
文档站。xLLM 是面向国产 AI 加速器的高性能大语言模型推理框架。
7+
8+
站点基于 Starlight 和 `starlight-theme-rapide` 构建，包含自定义顶部导航、
9+
中英文切换，以及用于将文档正文复制为 Markdown 的 `Copy page` 页面操作。
10+
11+
## 文档结构
12+
13+
文档内容按语言维护在两个并行目录中：
14+
15+
- 英文：`src/content/docs/en`
16+
- 简体中文：`src/content/docs/zh`
17+
18+
当前站点路由规则如下：
19+
20+
- `/` 重定向到 `/en/`
21+
- `/en/` 对应英文文档
22+
- `/zh/` 对应简体中文文档
23+
24+
新增或移动页面时，请尽量在两个语言目录中保持相同的相对路径，方便 Starlight
25+
在同一主题的不同语言版本之间切换。
26+
27+
## 项目结构
28+
29+
```text
30+
.
31+
├── astro.config.mjs # Starlight、语言、侧边栏和组件配置
32+
├── package.json # npm 脚本和依赖
33+
├── src/
34+
│ ├── assets/ # 站点级资源，例如 logo
35+
│ ├── components/ # Starlight 组件覆盖
36+
│ ├── content/
37+
│ │ └── docs/
38+
│ │ ├── en/ # 英文文档
39+
│ │ ├── zh/ # 简体中文文档
40+
│ │ └── assets/ # 文档图片和架构图
41+
│ ├── pages/index.astro # 从 / 重定向到 /en/
42+
│ └── styles/theme.css # 项目主题样式
43+
└── public/ # 静态公共资源
44+
```
45+
46+
## 本地开发
47+
48+
安装依赖：
49+
50+
```sh
51+
npm install
52+
```
53+
54+
启动本地开发服务：
55+
56+
```sh
57+
npm run dev
58+
```
59+
60+
构建生产站点：
61+
62+
```sh
63+
npm run build
64+
```
65+
66+
预览生产构建结果：
67+
68+
```sh
69+
npm run preview
70+
```
71+
72+
## 编辑文档
73+
74+
- 面向用户的文档内容放在 `src/content/docs/en` 和 `src/content/docs/zh`。
75+
- 同一个页面同时存在中英文版本时，尽量保持两个文件的相对路径一致。
76+
- 共享的文档图片放在 `src/content/docs/assets`。
77+
- 新增需要出现在导航中的章节时，更新 `astro.config.mjs` 中的 `sidebar`
78+
配置。
79+
- 提交前运行 `npm run build`，用于检查路由、frontmatter 和 Starlight
80+
内容问题。
81+
82+
## 相关仓库
83+
84+
- xLLM 源码：<https://github.com/xLLM-AI/xllm>

0 commit comments

Comments
 (0)