在基于hugo的博客上发表文章的步骤

概述

本文描述了在 hugo 发表文章的SOP（Standard Operating Procedure，标准作业程序）。

基本概念

hugo 是 golang 开发的一个博客框架程序。常用的功能有三种：

新建一个博客文档：hugo new XXX/XXX.md
启动本地博客服务器：hugo server -D
编译博客网站：hugo

基本上，在 windows 下维护基于 hugo 的博客，涉及到两个目录。可以分别称为「工作目录」和「公共目录」。

工作目录包含了图片、模板、原始博文（markdown文件）。
公共目录是一个完整的静态网站，包含所有要部署到服务器的静态文件（HTML、CSS、JS、图片等）。

习惯上，这两个目录各自保存为一个互相独立的 git 仓库。

基本流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


graph TD
    Start((开始))
    PullLatestWorkingDir[从远程仓库拉取最新工作目录]
    UpdateWorkingDir[在工作目录里编辑]
    PreviewWeb[预览网站效果]
    RemoveDraftMark[移除博文草稿标记]
    BuildStaticWeb[生成静态网站]
    PublishToServer[部署到服务器]
    BrowseWeb[浏览网站]
    CommitPushWorkingDir[同步工作目录到远程仓库]
    End((结束))
    Start --> PullLatestWorkingDir
    PullLatestWorkingDir --> UpdateWorkingDir
    UpdateWorkingDir --> PreviewWeb
    PreviewWeb --> UpdateWorkingDir
    PreviewWeb --> RemoveDraftMark
    RemoveDraftMark --> BuildStaticWeb
    BuildStaticWeb --> PublishToServer
    PublishToServer --> BrowseWeb
    BrowseWeb --> UpdateWorkingDir
    BrowseWeb --> CommitPushWorkingDir
    CommitPushWorkingDir --> End

流程详解

Step 1: 从远处仓库拉取最新工作目录

由于博客编辑可能在多台工作机上进行，每次编辑前需要从远程拉取最新工作目录。

Step 2: 在工作目录里编辑

包括hugo new XXX/XXX.md这类创建新博文的动作，编辑这个 XXX.md 博文，以及给这个博文打上标签。

博文的开头初始状态是这样的：

1
2
3
4
5


---
title: "XXX"
date: 2025-07-09T17:07:03+08:00
draft: true
---

这些并不是 markdown 的标准语法，而是一种叫做 Front Matter（前置元数据）的扩展语法，格式是YAML。

这里draft的值默认是true，表示这篇博文还处于草稿阶段。

这意味着直接hugo或者hugo server将看不到这篇博文。必须hugo server -D才能看到。

给博文打标签的方法是在前置元数据里添加tags内容。例如：

1
2
3
4
5
6
7
8
9


---
title: "XXX"
date: 2025-07-09T17:07:03+08:00
tags:
  - job
  - golang
  - software
draft: true
---

Step 3: 预览网站效果

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


D:\seedjyh\seedjyh.com>hugo server -D
Watching for changes in D:\seedjyh\seedjyh.com\{archetypes,content,static,themes}
Watching for config changes in D:\seedjyh\seedjyh.com\config.toml
Start building sites …
hugo v0.128.1-0ff542b4b9cc7b5cb425bbab8bdb5aace81d0c03+extended windows/amd64 BuildDate=2024-07-02T06:46:41Z VendorInfo=gohugoio


                   | EN
-------------------+-----
  Pages            | 64
  Paginator pages  |  4
  Non-page files   |  0
  Static files     | 40
  Processed images |  0
  Aliases          | 17
  Cleaned          |  0

Built in 111 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

然后就可以用网页浏览器（如Chrome）打开本地博客服务器检查效果了。

Step 4: 移除博文草稿标记

这一步很简单，就是把之前markdown开头的draft的值从true改成false。

Step 5: 生成静态网站

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


D:\seedjyh\seedjyh.com>hugo
Start building sites …
hugo v0.128.1-0ff542b4b9cc7b5cb425bbab8bdb5aace81d0c03+extended windows/amd64 BuildDate=2024-07-02T06:46:41Z VendorInfo=gohugoio


                   | EN
-------------------+-----
  Pages            | 55
  Paginator pages  |  3
  Non-page files   |  0
  Static files     | 40
  Processed images |  0
  Aliases          | 15
  Cleaned          |  0

Total in 133 ms

不带任何参数的 hugo，会在当前目录下生成一个public子目录。这个子目录并不属于「工作目录」，不要git add到工作目录里。这个子目录public就是「公共目录」，也叫「发布目录」，里面是一个完整的博客网站的静态文件集（HTML、CSS、JS、图片等）。

Step 6: 部署到服务器

将公共目录整个拷贝到自己的博客服务器上。

实践中，一般不会手动执行拷贝，而是在博客服务器上搭建一个git服务器，而公共目录自己也是个git仓库。当本地的公共目录被push到博客服务器上的git服务器时，用一个git钩子执行

1
2
3
4
5


[root@VM-16-14-centos hooks]# pwd
/home/git/blog.git/hooks
[root@VM-16-14-centos hooks]# cat post-receive 
#!/bin/sh
git --work-tree=/usr/local/www --git-dir=/home/git/blog.git checkout -f

意思是当这个git服务器收到推送时，就将整个git仓库的文件检出到/usr/local/www目录。而后者目录就是博客的根目录，由nginx路由到那个目录。

具体创建钩子的操作，参见我的另一篇博客《用hexo创建博客》。

Step 7: 浏览网站

用网页浏览器（如Chrome）打开真正博客服务器上的博客页面。一般来说，博客内容不太多的话，推送公共目录后立刻就能生效。

Step 8: 同步工作目录到远程仓库

「工作目录」包含了博客的全部源文件，尤其是博客文章（markdown）、模板和图片。

为了防止文件丢失，这个目录的修改（如添加博文）需要被同步（commit&push）到远端，就像第一步从远端拉取回来一样。

用技术改变世界。