feat(val-blog): scaffold containerized Hugo dev flow with compose and starter content

2026-08-13 17:00:21 +08:00
parent 95f2c06955
commit 2c9f4cbf67
15 changed files with 1272 additions and 0 deletions
@@ -0,0 +1,377 @@
+# 技术选型与架构方案
+
+## 1. 决策概览
+
+### 1.1 技术栈选型
+
+| 层级 | 技术选择 | 备选方案 | 决策理由 |
+|------|---------|---------|---------|
+| **静态生成器** | Hugo | Zola, Astro | 极速构建、成熟生态、Go模板 |
+| **主题框架** | 自定义 | PaperMod, Stack | 完全可控、符合品牌调性 |
+| **样式方案** | Tailwind CSS + 自定义CSS | SCSS/BEM | 原子化优先、暗色模式友好 |
+| **搜索** | Fuse.js (客户端) | Pagefind, Algolia | 零后端、轻量、隐私优先 |
+| **部署** | GitHub Pages + GitHub Actions | Vercel, Netlify | 简单免费、版本联动 |
+| **CMS(可选)** | 本地Markdown | Decap CMS | 纯文本优先、Git版本控制 |
+
+### 1.2 架构原则
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    架构决策原则                              │
+├─────────────────────────────────────────────────────────────┤
+│  1. 静态优先    →  零运行时依赖，最大可靠性                    │
+│  2. 渐进增强    →  核心内容无JS亦可访问                       │
+│  3. 内容即数据  →  Frontmatter驱动，结构化优先                │
+│  4. 工具链极简  →  单一二进制(Hugo)，减少依赖                 │
+│  5. 版本控制    →  Git为中心，内容+代码统一                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 系统架构
+
+### 2.1 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         内容生产层 (Content Layer)                   │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
+│  │  Markdown    │  │  Frontmatter │  │  Assets      │              │
+│  │  正文        │  │  元数据      │  │  图片/附件   │              │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
+└─────────┼─────────────────┼─────────────────┼──────────────────────┘
+          │                 │                 │
+          └─────────────────┼─────────────────┘
+                            ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      构建层 (Build Layer)                            │
+│  ┌───────────────────────────────────────────────────────────────┐ │
+│  │                     Hugo Static Generator                      │ │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │ │
+│  │  │ 内容解析 │→ │ 模板渲染 │→ │ 搜索索引 │→ │ 资源优化 │      │ │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │ │
+│  └───────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      输出层 (Output Layer)                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
+│  │  HTML    │  │  CSS/JS  │  │  Images  │  │  RSS/JSON│            │
+│  │  页面    │  │  样式    │  │  资源    │  │  Feed    │            │
+│  └────┬─────┘  └──────────┘  └──────────┘  └──────────┘            │
+└───────┼─────────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      部署层 (Deploy Layer)                           │
+│  ┌───────────────────────────────────────────────────────────────┐ │
+│  │              GitHub Pages (CDN + HTTPS)                        │ │
+│  └───────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 项目目录结构
+
+```
+val-blog/
+├── archetypes/              # 内容模板
+│   ├── journey.md          # 旅程记录模板
+│   ├── sketch.md           # 速记模板
+│   ├── gallery.md          # 图志模板
+│   └── essay.md            # 深度文模板
+├── assets/                  # 需处理的资源
+│   ├── css/
+│   │   ├── main.css        # 主样式
+│   │   ├── dark.css        # 暗色模式
+│   │   └── components/     # 组件样式
+│   ├── js/
+│   │   ├── search.js       # 搜索功能
+│   │   ├── theme.js        # 主题切换
+│   │   └── gallery.js      # 图片画廊
+│   └── images/
+│       └── logo.svg
+├── config.toml             # 站点配置
+├── content/                # 内容目录
+│   ├── _index.md          # 首页
+│   ├── about.md           # 关于页面
+│   ├── journey/           # 旅程记录
+│   ├── sketch/            # 速记
+│   ├── gallery/           # 图志
+│   ├── essay/             # 深度文
+│   └── series/            # 系列文章
+├── data/                   # 数据文件
+│   └── navigation.yaml
+├── layouts/                # 模板
+│   ├── _default/
+│   │   ├── baseof.html    # 基础模板
+│   │   ├── list.html      # 列表页
+│   │   └── single.html    # 单页
+│   ├── index.html         # 首页模板
+│   ├── partials/          # 模板片段
+│   │   ├── head.html
+│   │   ├── header.html
+│   │   ├── footer.html
+│   │   ├── navigation.html
+│   │   ├── search.html
+│   │   ├── theme-toggle.html
+│   │   └── pagination.html
+│   └── shortcodes/        # 短代码
+│       ├── gallery.html
+│       ├── timeline.html
+│       └── map.html
+├── static/                 # 静态文件
+│   ├── fonts/
+│   ├── images/
+│   ├── favicon.ico
+│   └── robots.txt
+└── themes/                 # 主题目录（如使用子主题）
+```
+
+---
+
+## 3. 功能模块设计
+
+### 3.1 功能矩阵
+
+| 功能 | 优先级 | 技术方案 | 状态 |
+|------|-------|---------|------|
+| 响应式布局 | P0 | Tailwind CSS | 待实现 |
+| 暗色模式 | P0 | CSS变量 + localStorage | 待实现 |
+| 中文排版优化 | P0 | typo.css + 自定义 | 待实现 |
+| 全文搜索 | P0 | Fuse.js + 索引构建 | 待实现 |
+| 标签系统 | P0 | Hugo Taxonomies | 待实现 |
+| 时间线视图 | P0 | 自定义模板 | 待实现 |
+| RSS/Atom | P0 | Hugo内置 | 待实现 |
+| JSON Feed | P1 | 自定义模板 | 待实现 |
+| 图片画廊 | P1 | 轻量JS + CSS Grid | 待实现 |
+| 文章系列 | P1 | Hugo Sections | 待实现 |
+| 阅读时间 | P1 | Hugo内置/自定义 | 待实现 |
+| 目录导航 | P1 | 自动生成TOC | 待实现 |
+| 相关文章 | P2 | 标签匹配 | 待实现 |
+| 阅读进度 | P2 | CSS/JS | 待实现 |
+| 代码高亮 | P2 | Prism.js/Chroma | 待实现 |
+| PWA支持 | P2 | Service Worker | 待实现 |
+| 评论系统 | P3 | Giscus(Utterances) | 待实现 |
+| Newsletter | P3 | 第三方服务 | 待实现 |
+
+### 3.2 暗色模式实现
+
+```css
+/* CSS变量定义 */
+:root {
+  /* 浅色模式 */
+  --bg-primary: #F7F5F0;
+  --bg-secondary: #FFFFFF;
+  --text-primary: #2D3E50;
+  --text-secondary: #5A6A7A;
+  --accent: #C9A961;
+  --border: #E5E1D8;
+}
+
+[data-theme="dark"] {
+  /* 暗色模式 */
+  --bg-primary: #1A1F2B;
+  --bg-secondary: #232936;
+  --text-primary: #D4D4D4;
+  --text-secondary: #8A94A6;
+  --accent: #D4B86A;
+  --border: #3A4150;
+}
+
+/* 系统偏好检测 */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    /* 暗色变量 */
+  }
+}
+```
+
+### 3.3 搜索架构
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  搜索实现方案                          │
+├──────────────────────────────────────────────────────┤
+│  构建时:                                              │
+│  └── Hugo模板生成 search-index.json                   │
+│      ├── title                                        │
+│      ├── content (摘要)                               │
+│      ├── tags                                         │
+│      ├── date                                         │
+│      └── permalink                                    │
+│                                                      │
+│  运行时:                                              │
+│  ├── 页面加载时异步获取 search-index.json             │
+│  ├── Fuse.js 初始化索引                               │
+│  ├── 输入时实时搜索                                   │
+│  └── 结果渲染 (标题+摘要+高亮)                        │
+│                                                      │
+│  优化:                                                │
+│  ├── 索引分片 (按年份/类型)                           │
+│  ├── 防抖 (300ms)                                     │
+│  └── 缓存至 sessionStorage                            │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. 内容模型
+
+### 4.1 Frontmatter规范
+
+```yaml
+---
+# 基础信息
+标题相关
+title: "文章标题"
+subtitle: "副标题（可选）"
+
+# 分类与标签
+categories: ["journey"]  # journey/sketch/gallery/essay
+tags: ["异世界", "魔法森林", "水晶洞穴"]
+series: "魔法大陆纪行"  # 系列名称（可选）
+series_order: 1        # 系列中的顺序
+
+# 时间与状态
+date: 2026-03-09T21:00:00+08:00
+lastmod: 2026-03-09T22:30:00+08:00
+draft: false
+featured: false        # 是否精选
+
+# 元数据
+author: "Val"
+location: "翡翠森林·北境"  # 故事发生地
+world: "Aethoria"       # 世界观/宇宙名称
+
+# 媒体
+cover: 
+  image: "/images/covers/forest-crystal.jpg"
+  alt: "水晶洞穴内部"
+  caption: "微弱的蓝光来自洞顶的水晶"
+
+gallery:  # 图志专用
+  - src: "/images/gallery/forest-01.jpg"
+    alt: "森林入口"
+  - src: "/images/gallery/forest-02.jpg"
+    alt: "水晶洞穴"
+
+# SEO
+description: "在翡翠森林深处发现的水晶洞穴"
+keywords: ["奇幻", "探险", "水晶洞穴"]
+
+# 交互
+comments: true
+toc: true              # 是否显示目录
+reading_time: true     # 是否显示阅读时间
+---
+```
+
+### 4.2 内容类型定义
+
+| 类型 | 目录 | 模板 | 特殊字段 |
+|------|------|------|---------|
+| 旅程记录 | `/journey/` | `journey/single.html` | location, route, timeline |
+| 速记 | `/sketch/` | `sketch/single.html` | mood, weather, time_of_day |
+| 图志 | `/gallery/` | `gallery/single.html` | gallery[], location |
+| 深度文 | `/essay/` | `essay/single.html` | abstract, references |
+
+---
+
+## 5. 部署方案
+
+### 5.1 GitHub Actions工作流
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.123.0'
+          extended: true
+          
+      - name: Build
+        run: hugo --minify
+        
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./public
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### 5.2 本地开发流程
+
+```bash
+# 1. 安装Hugo (macOS)
+brew install hugo
+
+# 2. 克隆项目
+git clone <repo> val-blog
+cd val-blog
+
+# 3. 启动开发服务器
+hugo server -D --bind 0.0.0.0
+
+# 4. 创建新内容
+hugo new content journey/2026/crystal-cave.md
+
+# 5. 构建 (生产)
+hugo --minify
+```
+
+---
+
+## 6. 性能预算
+
+| 指标 | 目标 | 最大允许 |
+|------|------|---------|
+| 首屏加载时间 | < 1.0s | 1.5s |
+| 可交互时间 | < 1.5s | 2.0s |
+| 首页总大小 | < 200KB | 300KB |
+| 单页总大小 | < 150KB | 250KB |
+| 搜索索引 | < 500KB | 1MB |
+| Lighthouse分数 | > 90 | 80 |
+
+---
+
+## 7. 变更记录
+
+| 版本 | 日期 | 变更内容 | 作者 |
+|------|------|---------|------|
+| v0.1.0 | 2026-03-09 | 初稿创建 | Val |