欢迎大家关注「几米宋」的微信公众号，公众号聚焦于云原生、AI、服务网格、工具教程、技术观察以及日常感悟等内容，更多内容请访问个人网站 jimmysong.io。

---

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

🔗 原文链接： https://jimmysong.io/blog/hugo-note-taking/

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

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

网站架构

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

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

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

1. 1. Content Layer（内容层）：包括 content/en、content/zh 等目录，用于存储不同语言的 Markdown 内容，以及 data/ 和 archetypes/ 文件夹，用于定义数据文件和内容模板。

2. 2. Theme & Layout Layer（主题与布局层）：包含 Hugo 的主题配置和布局文件，例如 layouts/ 和 layouts/shortcodes/，以及多语言支持文件 i18n/en.yaml 和 i18n/zh.yaml。

3. 3. Asset Pipeline（资源管道）：负责处理样式和脚本资源，包括 SCSS、JavaScript 和插件文件，使用 PostCSS 和 Node.js 进行编译和打包。

4. 4. Build & Tooling（构建与工具层）：包括构建脚本、Hugo CLI 和 Node.js 构建工具，用于生成静态网站。

5. 5. Static Output（静态输出）：生成的静态文件存储在 /public 目录中，作为最终部署的内容。

6. 6. CI/CD & Deployment（持续集成与部署）：通过 GitHub Actions 实现自动化测试，最终托管在 Cloudflare Pages 上。

7. 7. Analysis Tool（分析工具）：用于分析博客内容的工具集，生成 HTML 或文本格式的报告。

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

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

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

• • Typora：纯本地编辑，缺乏版本控制和协作能力

• • Notion：功能强大但体验臃肿，数据迁移困难，网络依赖严重

• • Obsidian：本地优先但仍局限在传统笔记范畴，缺乏发布和分享机制

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

这套组合的核心优势：

1. 1. 工具熟悉度：复用日常开发技能，零学习成本

2. 2. 版本控制：完整的 Git 历史记录，内容变更可追溯

3. 3. 协作友好：标准的 GitHub 工作流，支持多人协作

4. 4. 自动化：CI/CD 流程，从编辑到发布全自动

5. 5. 数据自主：完全掌控自己的内容和数据

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

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

核心插件推荐

插件	功能	为什么推荐
Hugo Language Support[2]	Hugo 语法高亮和 Shortcodes 支持	让 Hugo 模板语法清晰可读
Markdown All in One[3]	Markdown 编辑增强	快捷键、自动补全、目录生成
GitLens[4]	Git 历史可视化	内联显示每行代码的 Git 注释
GitHub Pull Requests[5]	GitHub 集成	在编辑器内管理 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^[6] 规范来标准化提交信息：

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. 1. 创建功能分支：git checkout -b feature/hugo-workflow-post

2. 2. 完成写作并本地测试

3. 3. 推送分支并创建 Pull Request

4. 4. 利用 GitHub Actions 自动检查（拼写、链接有效性等）

5. 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: DeploytoGitHubPages

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:SetupHugo
        uses:peaceiris/actions-hugo@v2
        with:
          hugo-version:'latest'
-name:Build
        run:hugo--minify
-name:DeploytoCloudflarePages
        uses:cloudflare/pages-action@v1
        with:
          apiToken:$
          accountId:$
          projectName:jimmysong-io
          directory: public

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

分支策略

• • main 分支：生产环境，每次推送自动部署

• • draft/* 分支：草稿分支，用于预览但不部署

• • feature/* 分支：功能开发分支，通过 PR 合并

数据分析：量化内容效果

本站通过自定义分析报告^[7]提供了对网站内容的深入洞察，包括文章发布频率、主题分布和双语关键词指标。通过这些数据，作者可以更好地理解读者需求，优化内容策略。

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

1. 1. 自动解析 Markdown 文件：遍历 content/ 目录，提取 Front Matter 数据

2. 2. 生成多维度统计：按时间、分类、标签等维度分析内容分布

3. 3. 可视化展示：生成热力图、趋势图等直观的数据呈现

4. 4. 支持多语言内容：同时分析中英文内容的发布情况

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

网站内容分析报告

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

1. 1. 月度发布热力图：清晰展示每月发布的文章数量，帮助我识别写作的活跃期和低谷期

2. 2. 内容分类统计：按标签和分类统计文章数量，了解内容的主题分布

3. 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 教程》^[9]：系统的 Hugo 实战指南

• • VS Code 官方文档^[10]：编辑器配置和插件使用

• • GitHub Flow 指南^[11]：标准的 GitHub 工作流程

• • GitHub Copilot 文档^[12]：通过 AI 提升开发效率

写在最后

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

这套工作流让我能够：

• • 用熟悉的工具高效创作

• • 用版本控制管理知识演进

• • 用自动化流程专注内容本身

• • 用数据分析优化内容策略

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

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

---

🔗 更多精彩内容

• • 🌐 个人网站：https://jimmysong.io

• • 🏠 云原生社区：https://cloudnativecn.com

• • 🎥 Bilibili：https://space.bilibili.com/206214

云原生社区

云原生社区 是国内最大的云原生技术社区，汇聚了众多技术专家和爱好者！

👥 如何加入：

• • 关注公众号【云原生社区动态】

• • 访问官网：cloudnativecn.com

• • 微信群：添加微信 jimmysong 备注"入群"

💫 如果这篇文章对你有帮助，欢迎点赞、分享给更多朋友！

📄 版权声明
本文首发于 Jimmy 的个人网站，遵循 CC BY-NC-SA 4.0 协议。转载请注明出处并保留作者信息。

引用链接

[1] GitDiagram:https://gitdiagram.com/
[2]Hugo Language Support:https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode
[3]Markdown All in One:https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
[4]GitLens:https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
[5]GitHub Pull Requests:https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github
[6]Conventional Commits:https://www.conventionalcommits.org/
[7]分析报告:https://jimmysong.io/analysis
[8]网站内容分析报告:https://jimmysong.io/analysis
[9]我的《Hugo 教程》:https://jimmysong.io/book/hugo-handbook/
[10]VS Code 官方文档:https://code.visualstudio.com/docs
[11]GitHub Flow 指南:https://guides.github.com/introduction/flow/
[12]GitHub Copilot 文档:https://docs.github.com/copilot
[13]《Hugo 教程》:https://jimmysong.io/book/hugo-handbook/