Add VitePress-based static Skills Catalog with site generator and Docker deployment

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

Dockerfile

@@ -0,0 +1,11 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM nginx:1.27-alpine
+COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

README.md

@@ -0,0 +1,89 @@
+# Gitea Skills Catalog (VitePress)
+
+一个纯静态的 Skills 展示站：构建时扫描 `skills/`，自动生成首页、分类页、详情页。
+
+## 目录约定
+
+```text
+skills/{category}/{skill-name}/SKILL.md
+```
+
+## 0) 先准备你的 Skills 内容
+
+把你自己的 skill 放进仓库，例如：
+
+```text
+skills/coding/python-debug/SKILL.md
+skills/devops/docker-helper/SKILL.md
+```
+
+> 页面是构建时生成的，所以新增/修改 skill 后，需要重新执行生成或 build。
+
+## 1) 本地运行（推荐）
+
+```bash
+npm install
+REPO_URL="https://your-gitea.example.com/your-user/your-repo" \
+REPO_BRANCH="main" \
+npm run dev
+```
+
+启动后访问：<http://localhost:4173>
+
+### 如果你只想先看生成结果
+
+```bash
+REPO_URL="https://your-gitea.example.com/your-user/your-repo" \
+REPO_BRANCH="main" \
+npm run generate
+```
+
+生成内容会写入：
+
+- `docs/index.md`
+- `docs/categories/*.md`
+- `docs/skills/{category}/{skill-name}.md`
+- `docs/.generated/catalog.mjs`（自动 nav/sidebar）
+
+## 2) 生产构建
+
+```bash
+REPO_URL="https://your-gitea.example.com/your-user/your-repo" \
+REPO_BRANCH="main" \
+npm run build
+```
+
+产物目录：`docs/.vitepress/dist`
+
+本地预览构建产物：
+
+```bash
+npm run preview
+```
+
+## 3) Docker 一键部署
+
+```bash
+docker compose up -d --build
+```
+
+默认访问：<http://localhost:8080>
+
+## 4) 环境变量
+
+- `REPO_URL`: Gitea 仓库地址（用于生成“查看源码”“下载 ZIP”链接）
+- `REPO_BRANCH`: 分支名（默认 `main`）
+- `REPO_ZIP_URL`: 自定义 ZIP 链接（默认 `${REPO_URL}/archive/${REPO_BRANCH}.zip`）
+
+## 5) 常见问题
+
+### npm install 403 / 无法访问 npm registry
+
+这是网络或镜像策略问题，不是项目本身问题。可尝试：
+
+```bash
+npm config set registry https://registry.npmmirror.com
+npm install
+```
+
+如果你的环境只能走内网镜像，请将 registry 切到你们内部 npm 源。

docker-compose.yml

@@ -0,0 +1,7 @@
+services:
+  skills-catalog:
+    build: .
+    container_name: skills-catalog
+    ports:
+      - "8080:80"
+    restart: unless-stopped

docs/.generated/catalog.mjs

@@ -0,0 +1,53 @@
+export const nav = [
+  {
+    "text": "首页",
+    "link": "/"
+  },
+  {
+    "text": "分类",
+    "link": "/categories/"
+  },
+  {
+    "text": "下载 ZIP",
+    "link": "https://gitea.example.com/your-user/skills-repo/archive/main.zip"
+  }
+];
+export const sidebar = {
+  "/categories/": [
+    {
+      "text": "分类",
+      "items": [
+        {
+          "text": "Coding",
+          "link": "/categories/coding"
+        },
+        {
+          "text": "Devops",
+          "link": "/categories/devops"
+        }
+      ]
+    }
+  ],
+  "/skills/": [
+    {
+      "text": "Coding",
+      "collapsed": false,
+      "items": [
+        {
+          "text": "python-debug",
+          "link": "/skills/coding/python-debug"
+        }
+      ]
+    },
+    {
+      "text": "Devops",
+      "collapsed": false,
+      "items": [
+        {
+          "text": "docker-helper",
+          "link": "/skills/devops/docker-helper"
+        }
+      ]
+    }
+  ]
+};

docs/.vitepress/config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitepress';
+import { nav, sidebar } from '../.generated/catalog.mjs';
+
+export default defineConfig({
+  lang: 'zh-CN',
+  title: 'Skills Catalog',
+  description: 'Gitea Skills 静态展示站',
+  cleanUrls: true,
+  themeConfig: {
+    logo: '🧩',
+    nav,
+    sidebar,
+    socialLinks: [{ icon: 'github', link: 'https://gitea.example.com/' }],
+    search: {
+      provider: 'local',
+    },
+  },
+});

docs/.vitepress/theme/custom.css

@@ -0,0 +1,39 @@
+:root {
+  --vp-c-brand-1: #7c3aed;
+  --vp-c-brand-2: #6d28d9;
+  --vp-c-brand-3: #5b21b6;
+}
+
+.VPFeature {
+  border: 1px solid color-mix(in srgb, var(--vp-c-brand-1) 20%, transparent);
+  border-radius: 16px;
+}
+
+.skill-meta {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.pill {
+  font-size: 12px;
+  background: color-mix(in srgb, var(--vp-c-brand-1) 14%, var(--vp-c-bg));
+  border: 1px solid color-mix(in srgb, var(--vp-c-brand-1) 30%, transparent);
+  border-radius: 999px;
+  padding: 4px 10px;
+}
+
+.skill-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin: 14px 0;
+}
+
+.action-link {
+  border: 1px solid var(--vp-c-brand-1);
+  border-radius: 10px;
+  padding: 6px 10px;
+  text-decoration: none;
+  font-weight: 600;
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,6 @@
+import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default {
+  extends: DefaultTheme,
+};

docs/categories/coding.md

@@ -0,0 +1,9 @@
+---
+title: Coding
+---
+
+# Coding
+
+共 1 个技能：
+
+- [python-debug](/skills/coding/python-debug)

docs/categories/devops.md

@@ -0,0 +1,9 @@
+---
+title: Devops
+---
+
+# Devops
+
+共 1 个技能：
+
+- [docker-helper](/skills/devops/docker-helper)

docs/categories/index.md

@@ -0,0 +1,8 @@
+---
+title: 分类
+---
+
+# 分类
+
+- [Coding](/categories/coding)
+- [Devops](/categories/devops)

docs/index.md

@@ -0,0 +1,34 @@
+---
+layout: home
+
+hero:
+  name: Skills Catalog
+  text: 基于 Gitea 仓库构建的静态技能展示站
+  tagline: 构建时自动扫描 skills/，无数据库、无后端、无运行时 API 请求
+  actions:
+    - theme: brand
+      text: 浏览全部技能
+      link: /categories/
+    - theme: alt
+      text: 下载仓库 ZIP
+      link: https://gitea.example.com/your-user/skills-repo/archive/main.zip
+
+features:
+  - icon: 🧭
+    title: 分类浏览
+    details: 按 category 自动聚合技能，快速定位目标内容
+  - icon: ⚡
+    title: 静态生成
+    details: 构建时扫描 SKILL.md 生成页面，部署简单稳定
+  - icon: 🔗
+    title: 源码直达
+    details: 每个技能页都可一键跳转到 Gitea 原始目录
+---
+
+## Coding
+
+- [python-debug](/skills/coding/python-debug)
+
+## Devops
+
+- [docker-helper](/skills/devops/docker-helper)

docs/skills/coding/python-debug.md

@@ -0,0 +1,39 @@
+---
+title: python-debug
+outline: deep
+---
+
+<div class="skill-meta">
+  <span class="pill">分类：coding</span>
+  <span class="pill">技能：python-debug</span>
+</div>
+
+# python-debug
+
+<div class="skill-actions">
+  <a class="action-link" href="https://gitea.example.com/your-user/skills-repo/src/branch/main/skills/coding/python-debug/SKILL.md" target="_blank" rel="noreferrer">查看 Gitea 源码</a>
+  <a class="action-link" href="https://gitea.example.com/your-user/skills-repo/archive/main.zip" target="_blank" rel="noreferrer">下载仓库 ZIP</a>
+</div>
+
+---
+
+---
+name: python-debug
+description: Python 调试最佳实践与排错流程。
+---
+
+# Python Debug
+
+## 适用场景
+
+- Traceback 分析
+- 复杂逻辑断点调试
+- 线上问题复现
+
+## 快速流程
+
+1. 最小复现
+2. 增加结构化日志
+3. 使用 `pdb` 或 IDE 断点
+4. 编写回归测试
+

docs/skills/devops/docker-helper.md

@@ -0,0 +1,39 @@
+---
+title: docker-helper
+outline: deep
+---
+
+<div class="skill-meta">
+  <span class="pill">分类：devops</span>
+  <span class="pill">技能：docker-helper</span>
+</div>
+
+# docker-helper
+
+<div class="skill-actions">
+  <a class="action-link" href="https://gitea.example.com/your-user/skills-repo/src/branch/main/skills/devops/docker-helper/SKILL.md" target="_blank" rel="noreferrer">查看 Gitea 源码</a>
+  <a class="action-link" href="https://gitea.example.com/your-user/skills-repo/archive/main.zip" target="_blank" rel="noreferrer">下载仓库 ZIP</a>
+</div>
+
+---
+
+---
+name: docker-helper
+description: Docker 构建、运行与镜像优化助手。
+---
+
+# Docker Helper
+
+## 能力
+
+- 生成多阶段 Dockerfile
+- 分析镜像体积
+- 编排本地调试容器
+
+## 常用命令
+
+```bash
+docker build -t my-app .
+docker run --rm -p 8080:8080 my-app
+```
+

package.json

@@ -0,0 +1,16 @@
+{
+  "name": "skills-catalog-site",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "node scripts/generate-site.mjs",
+    "predev": "npm run generate",
+    "dev": "vitepress dev docs --host 0.0.0.0 --port 4173",
+    "prebuild": "npm run generate",
+    "build": "vitepress build docs",
+    "preview": "vitepress preview docs --host 0.0.0.0 --port 4173"
+  },
+  "devDependencies": {
+    "vitepress": "^1.3.4"
+  }
+}