Skip to content

Commit de40631

Browse files
OXeuOXeu
authored
docs: migrate documentation from standalone repo to main repository (#419)
Move all docs from https://github.com/openRin/docs to docs/ directory Set up Rspress documentation site with bilingual support (zh/en) Include deploy guides, SEO/RSS configuration, changelog, and contribution guidelines Update README files to reference the new docs location Ensure code and documentation are now in sync within the same repository
1 parent ab13cc2 commit de40631

29 files changed

Lines changed: 2022 additions & 5 deletions

‎.github/workflows/docs.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Deploy Rspress site to Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/docs.yml'
9+
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
# Build job
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
30+
31+
- name: Set up Bun
32+
uses: oven-sh/setup-bun@v1
33+
34+
- name: Setup Pages
35+
uses: actions/configure-pages@v5
36+
37+
- name: Install dependencies
38+
working-directory: ./docs
39+
run: bun install
40+
41+
- name: Build with Rspress
42+
working-directory: ./docs
43+
run: bun run build
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v3
47+
with:
48+
path: docs/doc_build
49+
50+
# Deployment job
51+
deploy:
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
needs: build
56+
runs-on: ubuntu-latest
57+
name: Deploy
58+
steps:
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,7 @@ bun run dev
5757

5858
访问 http://localhost:5173 开始开发！
5959

60-
详细文档：
61-
- 📖 [本地开发指南](./docs/DEVELOPMENT.md)
62-
- 🚀 [部署指南](./docs/DEPLOY.md)
63-
- 🔧 [环境变量说明](./docs/ENV.md)
64-
- 📚 [完整文档](https://docs.openrin.org)
60+
详细文档：[docs.openrin.org](https://docs.openrin.org)
6561

6662
## Star History
6763

‎docs/.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
build/
7+
doc_build/
8+
9+
# Cache
10+
.cache/
11+
*.log
12+
13+
# IDE
14+
.vscode/
15+
.idea/
16+
17+
# OS
18+
.DS_Store
19+
Thumbs.db

‎docs/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Rin 文档
2+
3+
本文档站点使用 [Rspress](https://rspress.dev/) 构建。
4+
5+
## 开发
6+
7+
```bash
8+
# 安装依赖
9+
bun install
10+
11+
# 启动开发服务器
12+
bun dev
13+
14+
# 构建
15+
bun build
16+
17+
# 预览构建结果
18+
bun preview
19+
```
20+
21+
## 目录结构
22+
23+
```
24+
docs/
25+
├── docs/ # 文档内容
26+
│ ├── zh/ # 中文文档
27+
│ │ ├── guide/ # 指南
28+
│ │ │ ├── index.md # 简介
29+
│ │ │ ├── deploy.mdx # 部署指南
30+
│ │ │ ├── seo.md # SEO 配置
31+
│ │ │ ├── rss.md # RSS 配置
32+
│ │ │ ├── changelog.md # 更新日志
33+
│ │ │ └── contribution.md # 贡献指南
34+
│ │ ├── _meta.json # 中文导航配置
35+
│ │ └── env.md # 环境变量
36+
│ ├── en/ # 英文文档
37+
│ │ └── ... # 同上
38+
│ ├── index.md # 首页
39+
│ └── public/ # 静态资源
40+
├── package.json # 依赖配置
41+
├── rspress.config.ts # Rspress 配置
42+
└── tsconfig.json # TypeScript 配置
43+
```
44+
45+
## 文档同步
46+
47+
本文档与主仓库中的文档保持同步：
48+
- `docs/docs/zh/guide/deploy.mdx` ↔ `DEPLOY.md`
49+
- `docs/docs/zh/env.md` ↔ `ENV.md`
50+
- `docs/docs/zh/guide/seo.md` ↔ `SEO.md`
51+
- `docs/docs/zh/guide/rss.md` ↔ `RSS.md`
52+
- `docs/docs/zh/guide/contribution.md` ↔ `CONTRIBUTING_zh_CN.md`
53+
54+
修改时请同时更新两个位置的文档以确保一致性。

‎docs/bun.lock‎

Lines changed: 522 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/docs/en/_nav.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[
2+
{
3+
"text": "Guide",
4+
"items": [
5+
{ "text": "Introduction", "link": "/en/guide/" },
6+
{ "text": "Deploy", "link": "/en/guide/deploy" },
7+
{ "text": "SEO", "link": "/en/guide/seo" },
8+
{ "text": "RSS", "link": "/en/guide/rss" },
9+
{ "text": "Changelog", "link": "/en/guide/changelog" },
10+
{ "text": "Contribution", "link": "/en/guide/contribution" }
11+
]
12+
},
13+
{
14+
"text": "Configuration",
15+
"items": [
16+
{ "text": "Environment Variables", "link": "/en/env" }
17+
]
18+
}
19+
]

‎docs/docs/en/env.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Environment Variables List
2+
3+
## Frontend Environment Variables List
4+
5+
| Name | Required | Description | Default Value | Example Value |
6+
|--------------|----------|-----------------------------------------|---------------|----------------------------------------------------|
7+
| API_URL | Yes | Backend URL | None | http://localhost:3001 |
8+
| AVATAR | Yes | Avatar URL for the top left of the site | None | https://avatars.githubusercontent.com/u/36541432 |
9+
| NAME | Yes | Name & Title for the top left of the site | None | Xeu |
10+
| DESCRIPTION | No | Description for the top left of the site | None | Omnivore |
11+
| PAGE_SIZE | No | Default pagination limit | 5 | 5 |
12+
| RSS_ENABLE | No | Enable RSS (displays RSS link at the bottom of the site if enabled) | false | true |
13+
14+
**Deployment Environment Variables**
15+
16+
:::caution
17+
The following environment variables are required for deployment to Cloudflare Pages and cannot be modified.
18+
:::
19+
20+
| Name | Value | Description |
21+
|--------------------------|-----------------------------------------------------------|-------------------------------|
22+
| SKIP_DEPENDENCY_INSTALL | true | Skip the default npm install command |
23+
| UNSTABLE_PRE_BUILD | asdf install bun latest && asdf global bun latest && bun i | Install and use Bun for dependency installation |
24+
25+
## Backend Environment Variables List
26+
27+
**Plaintext Environment Variables**
28+
29+
:::note
30+
The following variables can remain unencrypted in Cloudflare Workers.
31+
:::
32+
33+
| Name | Required | Description | Default Value | Example Value |
34+
|-------------------|----------|-------------------------------------------------------|----------------|-------------------------------------------------------------------|
35+
| FRONTEND_URL | Temporarily required | Required for including comment article link in comment notification Webhook, can be left blank | None | https://xeu.life |
36+
| S3_FOLDER | Yes | File path for storing resources when uploading images | None | images/ |
37+
| S3_BUCKET | Yes | Name of the S3 bucket | None | images |
38+
| S3_REGION | Yes | Region of the S3 bucket, use 'auto' for Cloudflare R2 | None | auto |
39+
| S3_ENDPOINT | Yes | Endpoint address of the S3 bucket | None | https://1234567890abcdef1234567890abcd.r2.cloudflarestorage.com |
40+
| WEBHOOK_URL | No | Target address for sending Webhook notifications when a new comment is added | None | https://webhook.example.com/webhook |
41+
| S3_ACCESS_HOST | No | Access address of the S3 bucket | S3_ENDPOINT | https://image.xeu.life |
42+
| S3_CACHE_FOLDER | No | S3 cache folder (for SEO and high-frequency request caching) | cache/ | cache/ |
43+
44+
**Encrypted Environment Variables**
45+
46+
:::note
47+
All of the following variables are required (except Webhook) and must be encrypted after debugging in Cloudflare Workers. Unencrypted variables will be cleared during deployment if not listed in `wrangler.toml`.
48+
:::
49+
50+
| Name | Description | Example Value |
51+
|--------------------------|----------------------------------------------------------|-----------------------------------------------------------------|
52+
| RIN_GITHUB_CLIENT_ID | Client ID for GitHub OAuth | Ux66poMrKi1k11M1Q1b2 |
53+
| RIN_GITHUB_CLIENT_SECRET | Client secret for GitHub OAuth | 1234567890abcdef1234567890abcdef12345678 |
54+
| JWT_SECRET | Secret key required for JWT authentication, can be any regular format password | J0sT%Ch@nge#Me1 |
55+
| S3_ACCESS_KEY_ID | KEY ID required for accessing the S3 bucket, for Cloudflare R2 use an API token ID with R2 edit permissions | 1234567890abcdef1234567890abcd |
56+
| S3_SECRET_ACCESS_KEY | Secret required for accessing the S3 bucket, for Cloudflare R2 use an API token with R2 edit permissions | 1234567890abcdef1234567890abcd|

‎docs/docs/en/guide/_meta.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[
2+
"index",
3+
"deploy",
4+
"seo",
5+
"rss",
6+
"changelog",
7+
"contribution"
8+
]

‎docs/docs/en/guide/changelog.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Changelog
2+
3+
### v0.2.0 Updated on 2024-06-07
4+
5+
- Added `S3_CACHE_FOLDER` environment variable
6+
- Updated the list of encrypted environment variables, keeping only the essential ones
7+
- Encrypted variables can now be configured directly via GitHub
8+
- Updated GitHub variable configuration, added encrypted variables that must be configured through GitHub (S3 storage for SEO index storage)
9+
- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are now prefixed with `RIN_` (`RIN_GITHUB_CLIENT_ID`, `RIN_GITHUB_CLIENT_SECRET`) to solve the issue where GitHub variables cannot start with `GITHUB_`. Variables configured through the Cloudflare panel (`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`) are not affected.
10+
11+
## Migration Guide
12+
13+
For normal version updates without special instructions, simply synchronize the forked repository.
14+
15+
### v0.2.0 Migration Guide
16+
17+
- Due to the introduction of SEO optimization, it is necessary to configure S3 storage environment variables in GitHub. Therefore, you need to additionally configure the following environment variables in GitHub (plain text, add to Variables):
18+
19+
```ini
20+
SEO_BASE_URL=<SEO base URL for SEO indexing, defaults to FRONTEND_URL>
21+
SEO_CONTAINS_KEY=<SEO indexing only includes links starting with SEO_BASE_URL or containing the SEO_CONTAINS_KEY keyword, defaults to empty>
22+
S3_FOLDER=<Folder for storing S3 image resources, defaults to 'images/'>
23+
S3_CACHE_FOLDER=<S3 cache folder (for SEO and high-frequency request caching), defaults to 'cache/'>
24+
S3_BUCKET=<Name of the S3 bucket>
25+
S3_REGION=<Region of the S3 bucket, use 'auto' if using Cloudflare R2>
26+
S3_ENDPOINT=<S3 bucket endpoint address>
27+
S3_ACCESS_HOST=<S3 bucket access address, without trailing '/'>
28+
```
29+
30+
Additionally, add the following encrypted environment variables (encrypted, add to Secrets):
31+
32+
```ini
33+
S3_ACCESS_KEY_ID=<Your S3AccessKeyID>
34+
S3_SECRET_ACCESS_KEY=<Your S3SecretAccessKey>
35+
```
36+
37+
These environment variables were previously configured through the Cloudflare panel. Now they need to be migrated to GitHub. The new version's deployment GitHub Action will automatically upload them to Cloudflare, so you no longer need to configure these environment variables in the Cloudflare panel.

‎docs/docs/en/guide/contribution.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Contribute to Rin
2+
3+
We are happy to accept your patches and contributions to this project. You just need to follow some small guidelines.
4+
5+
## Commit-msg hooks
6+
7+
We have a sample commit-msg hook in `scripts/commit-msg.sh`. Please run the following command to set it up:
8+
9+
```sh
10+
ln -s ../../scripts/commit-msg.sh commit-msg
11+
```
12+
13+
On Windows, copy the `commit-msg.sh` file directly to `.git/hooks/commit-msg`.
14+
15+
```powershell
16+
cp .\scripts\commit-msg.sh .\.git\hooks\commit-msg
17+
```
18+
19+
This will run the following checks before each commit:
20+
21+
1. `tsc` Checks the code for syntax errors and unused variables and references.
22+
2. check that the commit message starts with one of the following: feature|chore|fix|docs|ci|style|test|pref
23+
24+
If you want to skip the hook, run `git commit` with the `--no-verify` option.
25+
26+
## Setting up your development environment
27+
28+
1. Fork & Clone the repository
29+
30+
2. Install [Node](https://nodejs.org/en/download/package-manager) & [Bun](https://bun.sh/)
31+
32+
3. Install dependencies
33+
```sh
34+
bun i
35+
```
36+
37+
4. Copy the `wrangler.example.toml` file to `wrangler.toml` and fill in the necessary information
38+
39+
:::tip
40+
Normally, you only need to fill in the `database_name` and `database_id` fields.\
41+
S3 configuration is not required, but if you want to use the image upload feature, you need to fill in the S3
42+
configuration.
43+
:::
44+
45+
5. Copy the `client/.env.example` file to `client/.env` and change the necessary configuration.
46+
47+
:::tip
48+
Typically, you only need to fill in `AVATAR`, `NAME` and `DESCRIPTION`.
49+
:::
50+
51+
6. Perform the database migration
52+
53+
:::tip
54+
If your database name (`database_name` in `wrangler.toml`) is not `rin`\
55+
Please modify the `DB_NAME` field in `scripts/dev-migrator.sh` before performing the migration
56+
:::
57+
```sh
58+
bun m
59+
```
60+
61+
7. Configuring the `.dev.vars' file
62+
Copy `.dev.example.vars` to `.dev.vars` and fill in the required information
63+
64+
:::tip
65+
Typically, you need to fill in the `RIN_GITHUB_CLIENT_ID` and `RIN_GITHUB_CLIENT_SECRET` as well as
66+
the `JWT_SECRET` fields.
67+
In the development environment, you need to create a separate GitHub OAuth service with a callback address
68+
of `http://localhost:11498/user/github/callback` \
69+
If you have changed the listening port of the server manually, please also change the port number in the callback
70+
address.
71+
:::
72+
73+
8. Start the development server
74+
```sh
75+
bun dev
76+
```
77+
78+
9. For better control of the development server, you can run the client and server dev commands in two separate
79+
terminals:
80+
```sh
81+
# tty1
82+
bun dev:client
83+
84+
# tty2
85+
bun dev:server
86+
```
87+
88+
## Committing Changes
89+
90+
1. for simple patches, they can usually be reviewed within 10 minutes during the day in the UTC+8 time zone. 2.
91+
92+
2. Do not force push minor changes after the PR is ready for review. Doing so forces maintainers to re-read your entire
93+
PR, which delays the review process. 3.
94+
95+
3. Always keep the CI green.
96+
97+
4. If the CI fails on your PR, do not push it. Even if you don't think it's the patch's fault. If something else is
98+
breaking the CI, help fix the root cause before you push.
99+
100+
*Start writing code happily!*
101+
102+
## Code review
103+
104+
All commits, including those from project members, need to be reviewed. We use GitHub pull requests for this purpose.
105+
For more information on using pull requests, see the GitHub Help.

0 commit comments

Comments
 (0)