像写代码一样记笔记：我的 VS Code + GitHub + Hugo 工作流

作为开发者，我们每天都在与代码编辑器、版本控制系统和自动化工具打交道。如果能把这些熟悉的工具应用到笔记管理上，会是什么体验？

经过一年多的实践，我构建了一套基于 VS Code + GitHub + Hugo 的笔记工作流，让记笔记变得像写代码一样高效、可追溯、可协作。这不只是换了个工具，而是整个思维方式的转变。

网站架构

下图展示了 jimmysong.io 网站的结构图。

注：本结构图使用 GitDiagram 生成，为历架构图，非最新架构。

这张结构图展示了 jimmysong.io 网站的整体架构，从内容层到部署层的各个模块之间的关系：

1. Content Layer（内容层）：包括 content/en、content/zh 等目录，用于存储不同语言的 Markdown 内容，以及 data/ 和 archetypes/ 文件夹，用于定义数据文件和内容模板。
2. Theme & Layout Layer（主题与布局层）：包含 Hugo 的主题配置和布局文件，例如 layouts/ 和 layouts/shortcodes/，以及多语言支持文件 i18n/en.yaml 和 i18n/zh.yaml。
3. Asset Pipeline（资源管道）：负责处理样式和脚本资源，包括 SCSS、JavaScript 和插件文件，使用 PostCSS 和 Node.js 进行编译和打包。
4. Build & Tooling（构建与工具层）：包括构建脚本、Hugo CLI 和 Node.js 构建工具，用于生成静态网站。
5. Static Output（静态输出）：生成的静态文件存储在 /public 目录中，作为最终部署的内容。
6. CI/CD & Deployment（持续集成与部署）：通过 GitHub Actions 实现自动化测试，最终托管在 Cloudflare Pages 上。
7. Analysis Tool（分析工具）：用于分析博客内容的工具集，生成 HTML 或文本格式的报告。

开发者通过编辑内容层和主题层的文件，结合资源管道和构建工具生成静态输出，最终通过 CI/CD 流程部署到线上。分析工具则为内容优化提供数据支持。

为什么选择这套工作流组合

在尝试了 Typora、Notion、Obsidian 等笔记工具后，我发现它们都有各自的局限性：

• Typora：纯本地编辑，缺乏版本控制和协作能力
• Notion：功能强大但体验臃肿，数据迁移困难，网络依赖严重
• Obsidian：本地优先但仍局限在传统笔记范畴，缺乏发布和分享机制

直到我意识到，作为开发者，我们已经有了一套完善的内容创作和管理工具链：

这套组合的核心优势：

1. 工具熟悉度：复用日常开发技能，零学习成本
2. 版本控制：完整的 Git 历史记录，内容变更可追溯
3. 协作友好：标准的 GitHub 工作流，支持多人协作
4. 自动化：CI/CD 流程，从编辑到发布全自动
5. 数据自主：完全掌控自己的内容和数据

VS Code：打造完美的写作环境

VS Code 不只是代码编辑器，配合合适的插件，它也是优秀的 Markdown 写作环境。

核心插件推荐

写作体验优化

启用 GitLens 后，编辑器会在每行末尾显示最后一次提交的信息，让我清楚知道每段内容的修改历史：

title: "Hugo 教程第一章"     // feat: 添加 Hugo 基础教程，Jimmy, 2 days ago
date: 2025-07-03            // fix: 修正发布日期，Jimmy, 1 day ago  

配合 Markdown All in One 插件，我可以快速生成目录、格式化表格、使用快捷键插入链接等，编辑体验比大多数专业 Markdown 编辑器还要流畅。

集成终端的威力

VS Code 的集成终端让我可以无缝切换编辑和命令行操作：

# 创建新文章
hugo new blog/new-post/index.md

# 本地预览
hugo server --drafts --bind 0.0.0.0

# 提交更改
git add .
git commit -m "feat: 添加新的技术文章"
git push

这种"编辑 - 预览 - 提交"的流程已经深深印在开发者的肌肉记忆里，应用到笔记写作上自然而然。当然直接使用 GitHub 的插件来自动生成 commit 消息和管理分支我也推荐的，毕竟使用起来更加便利。

GitHub：版本控制与协作的核心

GitHub 不仅提供版本控制，更是整个协作流程的中枢。

规范化的 Commit Message

借鉴软件开发的最佳实践，我使用 Conventional Commits 规范来标准化提交信息：

feat(blog): 添加 Hugo 工作流文章
fix(theme): 修复移动端导航菜单样式
docs(readme): 更新项目说明文档
chore(deps): 升级 Hugo 到最新版本

这样的提交历史不仅清晰易读，还可以配合工具自动生成 CHANGELOG。

Issue 驱动的内容规划

我把文章想法、todo 事项都记录在 GitHub Issues 中：

• 使用 enhancement 标签标记新文章想法
• 使用 bug 标签标记需要修正的内容
• 使用 question 标签记录需要研究的问题

在提交时通过 fixes #123 关联对应 Issue，形成完整的需求 - 开发 - 交付闭环。

Pull Request 工作流

即使是个人项目，我也会使用 PR 工作流来管理重要的内容更新：

1. 创建功能分支：git checkout -b feature/hugo-workflow-post
2. 完成写作并本地测试
3. 推送分支并创建 Pull Request
4. 利用 GitHub Actions 自动检查（拼写、链接有效性等）
5. 预览部署成功后合并到主分支

这个流程虽然看起来复杂，但对于重要文章很有价值——它给了我一个"最后检查"的机会。

Hugo：内容与展示的完美结合

Hugo 的强大之处在于它既保持了 Markdown 的简洁性，又提供了丰富的扩展能力。

结构化的内容组织

我的 Hugo 项目结构反映了清晰的内容分层：

content/
├── zh/                 # 中文内容
│   ├── blog/           # 博客文章
│   ├── book/           # 电子书籍
│   ├── notice/         # 通知公告
│   └── podcast/        # 播客内容
├── en/                 # 英文内容
└── data/               # 结构化数据
    └── terms.yaml      # 术语定义

每篇文章的 Front Matter 都包含丰富的元数据：

---
title: "像写代码一样记笔记"
date: 2025-07-05T16:40:00+08:00
categories: ["工具教程"]
tags: ["Hugo", "VS Code", "GitHub"]
description: "描述信息"
image: "images/feature.png"
---

这些元数据不仅用于渲染，更是我后续数据分析的重要基础。

多语言支持

作为技术博客，支持中英双语可以扩大读者群体。Hugo 的内置国际化功能让这变得简单：

# config.yaml
defaultContentLanguage: "zh"
languages:
  zh:
    languageName: "中文"
    weight: 1
  en:
    languageName: "English"
    weight: 2

自动化部署：从提交到发布

整个发布流程完全自动化，体现了 DevOps 思维在内容管理中的应用。

GitHub Actions 工作流

我的 .github/workflows/deploy.yml 配置了完整的 CI/CD 流程：

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          
      - name: Build
        run: hugo --minify
        
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: jimmysong-io
          directory: public

这意味着我只需要专注于写作，发布过程完全无需人工干预。不过自动将网站托管平台从 GitHub Pages 迁移到 Cloudflare Pages 之后，GitHub Action 仅仅作为测试和自动化工具了，不再用于发布。

分支策略

• main 分支：生产环境，每次推送自动部署
• draft/* 分支：草稿分支，用于预览但不部署
• feature/* 分支：功能开发分支，通过 PR 合并

数据分析：量化内容效果

作为开发者，我习惯用数据驱动决策。我开发了自己的内容分析工具：

1. 自动解析 Markdown 文件：遍历 content/ 目录，提取 Front Matter 数据
2. 生成多维度统计：按时间、分类、标签等维度分析内容分布
3. 可视化展示：生成热力图、趋势图等直观的数据呈现
4. 支持多语言内容：同时分析中英文内容的发布情况

访问网站内容分析报告，深入分析 Jimmy 的写作历程与内容分布。

网站内容分析报告

我的分析报告包含以下内容：

1. 月度发布热力图：清晰展示每月发布的文章数量，帮助我识别写作的活跃期和低谷期
2. 内容分类统计：按标签和分类统计文章数量，了解内容的主题分布
3. 访问趋势分析：结合 Umami 数据，分析访问量和用户行为模式

比如我生成的「月度发布热力图」，可以很清楚的看到历年来每月发布的文章数量，当然你自己拥有所有数据，可以有很多玩法，我还打算用它生成 RAG（检索增强生成），然后构建自己的数字分身。

未来规划

未来，我计划将这些数据用于：

• 智能内容推荐：基于用户行为推荐相关文章
• RAG 模型训练：利用历史内容训练个人知识库
• 内容策略优化：通过数据分析指导内容创作方向

实际工作流演示

让我用一个具体例子展示这套工作流的日常使用：

1. 灵感捕获

# 在 GitHub 创建 Issue
gh issue create --title "Hugo 工作流文章" --body "分享我的笔记工作流经验"

2. 内容创作

# 创建新文章
hugo new blog/hugo-workflow/index.md

# 在 VS Code 中编辑，GitLens 显示历史信息
# Markdown All in One 提供编辑增强

3. 本地预览

# 启动本地服务器
hugo server --drafts --bind 0.0.0.0 --port 1313

# 浏览器访问 http://localhost:1313 预览效果，也可以访问主机域名，还可以从移动端访问

4. 版本控制

# 规范化提交
git add .
git commit -m "feat(blog): 添加 Hugo 工作流分享文章

详细介绍了 VS Code + GitHub + Hugo 的完整工作流，
包括工具配置、自动化部署和数据分析等方面。

fixes #123"

5. 自动发布

# 推送到 GitHub
git push origin main

# GitHub Actions 自动构建和部署
# 2 分钟后文章上线

工作流的核心价值

• 开发技能复用：将日常开发工具和技能应用到笔记管理中，降低学习成本。
• 规范化管理：
  • 使用标准的提交规范（如 Conventional Commits）记录内容变更。
  • 采用分支策略（如 main、draft/*、feature/*）管理内容开发和发布流程。
• 自动化流程：通过 GitHub Actions 实现从编辑到发布的全自动化，减少人工干预。
• 协作与审查：
  • 借助 GitHub 工作流支持多人协作和代码审查。
  • 使用 Issue 和 Pull Request 跟踪需求和内容更新。
• 数据驱动优化：
  • 通过操作日志和数据分析量化内容效果。
  • 基于分析结果优化内容策略和创作方向。
• 完整的历史记录：Git 提供了内容变更的完整历史，支持版本回滚和追溯。
• 高效的内容管理：统一的工具链和流程让内容创作更加系统化和可持续。

推荐资源与下一步

如果你也想尝试这套工作流，推荐从以下资源开始：

• 我的《Hugo 教程》：系统的 Hugo 实战指南
• VS Code 官方文档：编辑器配置和插件使用
• GitHub Flow 指南：标准的 GitHub 工作流程
• GitHub Copilot 文档：通过 AI 提升开发效率

写在最后

像写代码一样记笔记，这不只是一句口号，而是一种思维方式的转变。当我们把软件开发的最佳实践应用到内容创作上，记笔记就从个人行为变成了系统工程。

这套工作流让我能够：

• 用熟悉的工具高效创作
• 用版本控制管理知识演进
• 用自动化流程专注内容本身
• 用数据分析优化内容策略

如果你也是开发者，强烈建议尝试这套工作流。它会让你重新认识笔记管理，也会让你的知识体系更加系统和可持续。

💡 开始尝试：克隆一个 Hugo 模板仓库，安装推荐的 VS Code 插件，然后开始你的第一篇文章吧！详细的搭建指南在我的《Hugo 教程》中都有覆盖。