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

从 VS Code 编辑器到 GitHub 版本控制，再到 Hugo 静态网站生成，我的这套工作流让记笔记变得像写代码一样高效而优雅。

2025/07/05 • 个人动态 • 18 分钟 • 3856 字

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

经过一年多的实践，我构建了一套基于 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 写作环境。

核心插件推荐

插件功能为什么推荐
Hugo Language SupportHugo 语法高亮和 Shortcodes 支持让 Hugo 模板语法清晰可读
Markdown All in OneMarkdown 编辑增强快捷键、自动补全、目录生成
GitLensGit 历史可视化内联显示每行代码的 Git 注释
GitHub Pull RequestsGitHub 集成在编辑器内管理 PR 和 Issue

写作体验优化

启用 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 模板仓库，安装推荐的 VS Code 插件，然后开始你的第一篇文章吧！详细的搭建指南在我的《Hugo 教程》中都有覆盖。

阅读 Hugo 教程

文章信息

最后更新 2025/07/26 编辑页面 Hugo 静态网站 笔记管理 VS Code GitHub 工作流

文章导航

相关文章

评论区