init docs

Author: sjjian

.github/workflows/pages.yml

@@ -0,0 +1,59 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - dev_0_6_0
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/site/package-lock.json
+
+      - name: Install
+        working-directory: docs/site
+        run: npm ci
+
+      - name: Build
+        working-directory: docs/site
+        env:
+          REPO_NAME: ${{ github.event.repository.name }}
+          BASE_PATH: /${{ github.event.repository.name }}/
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

docs/.gitignore

@@ -0,0 +1,9 @@
+site/node_modules/
+site/.astro/
+site/.cache/
+site/dist/
+
+# 避免误提交旧的 /docs 发布产物
+index.html
+logo.png
+assets/

docs/README.md

@@ -0,0 +1,56 @@
+# openhare 官网（静态站点）
+
+本目录用于 GitHub Pages 发布的静态官网。
+
+## 目录结构
+
+- `docs/`：官网文档目录
+- `docs/site/`：Astro 项目源码（开发、构建用）
+
+## 语言
+
+- 中文：`/`
+- English：`/en/`
+
+## 本地开发
+
+```bash
+cd docs/site
+npm install
+npm run dev
+```
+
+## 构建（输出到 docs/site/dist）
+
+```bash
+cd docs/site
+npm run build
+```
+
+构建完成后应能看到：
+
+- `docs/site/dist/index.html`
+- `docs/site/dist/assets/...`
+
+> 注意：构建产物不提交到主分支，由 GitHub Actions 负责构建并发布到 GitHub Pages。
+
+## GitHub Pages 发布
+
+在 GitHub 仓库中打开 **Settings → Pages**：
+
+- **Source**：GitHub Actions
+
+然后推送代码即可自动构建并发布。
+
+## 配置 base 路径（重要）
+
+如果你的 Pages 地址是 `https://<user>.github.io/<repo>/`，则需要设置 base 为 `/<repo>/`。
+
+本项目在 CI 中会根据仓库名自动注入 `BASE_PATH`（例如 `/openhare/`），本地默认按仓库名 `openhare` 配置。需要调整时，编辑：
+
+- `docs/site/astro.config.mjs`
+
+对应的 Pages 工作流文件：
+
+- `.github/workflows/pages.yml`
+

docs/site/astro.config.mjs

@@ -0,0 +1,27 @@
+import { defineConfig } from 'astro/config';
+
+/**
+ * GitHub Pages 通常发布在子路径：
+ *   https://<user>.github.io/<repo>/
+ * 因此需要设置 base 为 `/<repo>/`。
+ */
+const repoName = process.env.REPO_NAME ?? 'openhare';
+const base = process.env.BASE_PATH ?? `/${repoName}/`;
+
+export default defineConfig({
+  // 构建产物输出到本项目 dist，由 GitHub Actions 发布到 Pages
+  outDir: './dist',
+  base,
+  build: {
+    // 将默认的 `_astro/` 改为更通用的目录名
+    assets: 'assets',
+  },
+
+  // dist 可安全清空
+  vite: {
+    build: {
+      emptyOutDir: true,
+    },
+  },
+});
+