用Emacs和Hugo打造完美博客

1 简介

#

本文章主要是记录自己用Emacs和Hugo搭建写博客工作环境的过程，为了今后更换电脑之后，可以参照这篇文章轻松重新搭建写博客的工作环境。

工作环境流程： Emacs org mode写博客 ↪️ ox-hugo将org导出为md文件 ↪️ git提交到远程仓库。

文章的结构主要包括三方面，Emacs写和导出博客、Hugo安装和配置、托管和部署。

2 Emacs写和导出博客

#

2.1 org mode写博客

#

用org mode编写博客，也可以用别的工具编写，只要能导出为md文件即可。

2.2 ox-hugo导出为md文件

#

1. 安装和配置ox-hugo

   (use-package ox-hugo
     :ensure t
     :after ox
     :config
     (setq org-hugo-base-dir "/mnt/f/blog/blowfish-hugo-source-file/")
     (setq org-hugo-export-with-section-numbers t)
     ;; 导出四级标题
     (setq org-export-headline-levels 4)
     )
   

   • “org-hugo-base-dir”设置为Hugo的源文件目录，也就是存放“content”文件夹的目录
   • “org-hugo-export-with-section-numbers”可以设置将几级标题导出为md文件的标题

2. 使用ox-hugo导出org文件为md文件

   • 在org文件中使用快捷键“C-c C-e H h”将org文件导出为md文件
   • 本文使用一个org文件对应一篇博客的方式
   • ox-hugo会将org文件导出为md文件，并将其放在“org-hugo-base-dir”目录下的“content”目录中

2.3 选项设置

#

可以在org文件的头部设置一些选项，以控制导出的md文件的格式和内容。例如：

2.3.1 HUGO_SECTION

#

• 指定子目录
• 示例：learning_notes/蚂蚁摄影_22级风光摄影大师班_学习笔记

2.3.2 EXPORT_FILE_NAME

#

• 指定导出的md文件名
• 示例：index.md
• 注意
  • 如果不指定，默认使用org文件名
  • 这里指定为“index.md”是为了配合blowfish主题的目录结构

2.3.3 HUGO_CATEGORIES

#

• 指定文章的分类
• 示例：摄影

2.3.4 HUGO_TAGS

#

• 指定文章的标签
• Hugo的标签

2.3.5 HUGO_AUTHOR

#

• 指定文章的作者

2.3.6 title

#

• 指定文章的标题

2.4 使用yasnippet快速插入头部选项

#

2.4.1 简介

#

yasnippet是Emacs的一个强大的模板系统，可以用来快速插入一些常用的代码片段。

2.4.2 安装和配置

#

2.4.2.1 添加Emacs配置文件

#

(use-package yasnippet
  :ensure t
  :defer t
  :init
  (yas-global-mode 1)
  )

2.4.2.2 创建模板

#

1. 在“~/.emacs.d/snippets/”目录下创建一个名为hugo-note的文件
   • 文件名可自定义
   • 不要加后缀名
2. 在文件中写入模板内容，例如：

   # name: Hugo 学习笔记模板
   # key: hugo-note
   # --
   #+HUGO_SECTION: ${1:}/${2:}
   #+EXPORT_FILE_NAME: index.md
   #+HUGO_CATEGORIES: ${3:}
   #+HUGO_TAGS: ${4:}
   #+HUGO_AUTHOR: ${5:Dyingdong}
   #+DESCRIPTION: ${6:}
   #+TITLE: ${7:}
   $0
   

2.4.2.3 使用模板

#

1. 在org文件中输入“hugo-note”，然后按下Tab键
2. yasnippet会自动展开模板，并将光标定位到第一个占位符位置
3. 按顺序填写占位符内容

3 Hugo安装和配置

#

3.1 安装Hugo

#

本文是在Windows11上使用wsl（Ubuntu24.01）安装Hugo的，具体安装方法自行百度。

3.2 主题配置

#

3.2.1 配置教程

#

1. 使用 Blowfish和 Hugo 构建你的主页
2. 其它教程：Blowfish文档

3.2.2 个性化配置

#

3.2.2.1 themes/blowfish/i18n/zh-cn.toml

#

可以修改页面中的主题组件名称，例如：“最近的文章”、“显示更多”等。

3.2.2.2 修改多极列表样式

#

1. 在 assets/css/custom.css 中添加样式（如果没有该文件，请创建）：

   /* 恢复多级列表样式 */
   .prose ul {
       list-style-type: disc; /* 一级列表：实心圆点 */
   }
   
   .prose ul ul {
       list-style-type: circle; /* 二级列表：空心圆点 */
   }
   
   .prose ul ul ul {
       list-style-type: square; /* 三级列表：实心方块 */
   }
   
   /* 有序列表样式（可选） */
   .prose ol {
       list-style-type: decimal; /* 1. 2. 3. */
   }
   
   .prose ol ol {
       list-style-type: lower-alpha; /* a. b. c. */
   }
   
   .prose ol ol ol {
       list-style-type: lower-roman; /* i. ii. iii. */
   }
   

2. Blowfish配置列表样式的文件： themes/blowfish/assets/css/compiled/main.css
3. 为什么这样修改？
   • Blowfish 主题重置了列表样式：

     ol, ul, menu {
         list-style: none; /* 移除默认列表样式 */
     }
     

   • 因此，需要在 prose 类中重新定义列表样式
4. 覆盖 Blowfish 的默认列表样式如果主题的 CSS 优先级较高，可以加上 !important：

   .prose ul {
       list-style-type: disc !important;
   }
   

3.2.3 配置过程中需要注意的点

#

3.2.3.1 content目录下的文件名需要与配置文件中保持一致

#

1. 文件名尽量不要用空格连接，可以使用“_”连接，以“learning_notes”为例
2. 需要与如下配置保持一致
   • menus.zh-cn.toml

     [[main]]
     name = "学习笔记"
     parent = "摄影"
     pageRef = "learning_notes"
     weight = 20
     

   • params.toml

     mainSections = ["learning_notes"]
     [homepage]
     showMoreLinkDest = "/learning_note/"
     

3.2.4 偷懒方法

#

1. 可以从GitHub上下载Blowfish主题的源文件，在示例的基础上进行修改。
2. 链接：https://github.com/nunocoracao/blowfish/tree/main/exampleSite
3. 注意：这种方法也需要在熟悉Blowfish主题的目录结构和配置文件的基础上使用

4 托管和部署

#

4.1 将Hugo源文件托管到GitHub

#

在GitHub上创建一个新的私有仓库，将Hugo的源文件上传到该仓库中。

4.2 将博客托管到Cloudflare

#

由于GitHub 的Pages不太好用，本文借鉴网上的方法，使用Cloudflare的Pages来托管博客。

4.2.1 访问 Cloudflare 并登录

#

4.2.2 创建新的Pages项目

#

1. 在Cloudflare的主界面找到“计算(Workers)”
2. 选择“Workers和Pages”
3. 创建新的Pages项目
4. 选择“导入现有Git存储库”
5. 根据提示连接GitHub账户，选择之前创建的Hugo源文件的GitHub仓库
6. 设置构建和部署（创建完后可以修改）

   • 项目名称：可以自定义

   • 生产分支：选择“main”

   • 构建设置：

     • 框架预设：选择“Hugo”
     • 构建命令：hugo
     • 构建输出目录：public

   • 环境变量（高级）：可自定义Hugo版本

     

7. 点击“保存并部署”按钮
8. 等待部署完成，部署成功之后可以访问Cloudflare提供的域名查看博客

4.2.3 后续使用

#

• 每次修改Hugo源文件后，提交到GitHub仓库
• Cloudflare会自动检测到GitHub仓库的变化，并重新部署博客