如何用 hugo 和 org-mode 搭建个人博客

Mushi 收录于类别 Learning

2022-04-23 2023-01-13 约 2926 字预计阅读 6 分钟

关于本文

这篇文章主要介绍怎么用 orgmode, hugo, github pages 来搭建一个个人博客.

如果你不是 emacs 用户, 你可以不看 org-mode 的部分, 直接用 markdown 来写就好了.

如果你怕折腾的话, 这篇文章也不适合你.

用到的工具和操作流程

工具

工具	介绍
`org-mode`	一个强大的文本语言, 主要在 `emacs` 上使用
`ox-hugo`	一个 `emacs` 的插件
`hugo`	开源的静态站点生成器, 用于构建个人博客
`LoveIt`	hugo 的一个主题
`github pages`	我们可以把博客托管到这上面来
`git`	用来发布/托管博客

操作流程

在 emacs 上安装 ox-hugo, 并做适当配置
安装 hugo, 初始化, 创建一个新的网站
安装 hugo 主题 LoveIt, 做些配置
创建你的文章并用 ox-hugo 转换成 markdown 格式
在本地预览你的网站
使用 git 托管你的网站到 github pages

第一步在 `emacs` 上安装 `ox-hugo`

如果你使用 Markdown 写博客, 可以跳过这第一步的内容.

关于 ox-hugo

ox-hugo 是个 emacs 插件, 他将 org 内容转换成 hugo 兼容的 Markdown 格式, 并将一些 org 头部文件转换成 hugo 识别的前置参数.

安装 `ox-hugo`

普通安装

你可以在你的配置中加上如下代码

1
2


(with-eval-after-load 'ox
  (require 'ox-hugo))

通过使用 use-package 来安装

将下面这段代码放到你的配置中

1
2
3
4


(use-package ox-hugo
  :ensure t   ;Auto-install the package from Melpa
  :pin melpa  ;`package-archives' should already have ("melpa" . "https://melpa.org/packages/")
  :after ox)

在 doom-emacs 中安装

在 doom 配置文件 init.el 中, 取消 org 一行的注释, 在下面添加 hugo 支持即可. 或者在 package.el 配置文件中写下

1

(package! ox-hugo)

详细内容可以参考 doom-emacs 文档中关于安装插件的这部分

`ox-hugo` 的使用与配置

使用 `ox-hugo`

如果你对 emacs 很熟悉的话, 想必安装不难. 之后在写一篇 org 文章的时候按快捷键 C-c+C-e 就会呼出交互式的导出选项了, 你也可以 M-x org-export-dispatch, 导出选项中有一项是 Export to Hugo-compatible Markdown, 就是我们要用的.

这时候, 如果我们按 H 再按 h 即可将 org 文件导出为 Markdown 文件了.

配置 `ox-hugo`

基本的功能无须配置即可使用, 更多个性化配置详见 ox-hugo

第二步安装 `hugo`, 并做初始化

安装 `hugo`

我这里以 Mac 的 Homebrew 为例, 其他设备参考如何安装 hugo

1

brew install hugo

之后验证下是否安装成功

1

hugo version

如果你不理解上面这些代码的意义的话, 你就不应该浪费时间继续看这篇文章了

如果你安装失败的话, 大概率是网络问题, 你需要想办法解决.

初始化 `hugo` (创建一个新的网站)

Hugo 提供了一个 new 命令来创建一个新的网站, 切换到家目录(你也可以自己选择) 后, 执行下面代码

1
2


hugo new site blog
cd blog

这里我们在家目录新建了一个 blog 文件夹, 这个文件夹就是我们的博客的全部内容.

初始化目录结构如下

1
2
3
4
5
6
7
8
9


./
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

第三步安装一个自己喜欢的 `hugo` 主题(以 `LoveIt` 为例)

你可以选择一个自己喜欢的 hugo 主题安装, 见 hugo 主题列表

这里我以 LoveIt 这款主题为例, 对于我这种新手, 它有很详实的文档和很棒的中文支持.

安装主题 `LoveIt`

手动安装

LoveIt 的主题仓库是: https://github.com/dillonzq/LoveIt

下载最新的 .zip 文件并解压放到 themes 目录下.

git clone

1

git clone https://github.com/dillonzq/LoveIt.git themes/LoveIt

初始化你的项目目录为 git 仓库, 并且把主题仓库作为网站目录的子模块

这种方法我比较推荐, 关于 git 子模块的介绍见 git 子模块

1
2


git init
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

`LoveIt` 的配置

这里我们直接修改 config.toml 这个文件, 它决定了网站的默认配置.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


baseURL = "http://example.org/"
# [en, zh-cn, fr, ...] 设置默认的语言
defaultContentLanguage = "zh-cn"
# 网站语言, 仅在这里 CN 大写
languageCode = "zh-CN"
# 是否包括中日韩文字
hasCJKLanguage = true
# 网站标题
title = "我的全新 Hugo 网站"

# 更改使用 Hugo 构建网站时使用的默认主题
theme = "LoveIt"

[params]
  # LoveIt 主题版本
  version = "0.2.X"

[menu]
  [[menu.main]]
    identifier = "posts"
    # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标
    pre = ""
    # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标
    post = ""
    name = "文章"
    url = "/posts/"
    # 当你将鼠标悬停在此菜单链接上时, 将显示的标题
    title = ""
    weight = 1
  [[menu.main]]
    identifier = "tags"
    pre = ""
    post = ""
    name = "标签"
    url = "/tags/"
    title = ""
    weight = 2
  [[menu.main]]
    identifier = "categories"
    pre = ""
    post = ""
    name = "分类"
    url = "/categories/"
    title = ""
    weight = 3

# Hugo 解析文档的配置
[markup]
  # 语法高亮设置 (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false 是必要的设置 (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

关于更详细的完整配置可以查看 LoveIt 的配置文档完整配置

第四步创建一篇你的文章

使用 `ox-hugo` 插件, 将你写的 `org` 文档转换成 `Markdown` 文档

如果你使用 Markdown 写作可以跳过这部分

我们先在博客目录下建立一个文件夹来存放我们的 org 文件

1

cd blog && mkdir org

切换到 ./org 目录下, 新建 org 文件, 如 我的第一篇博客.org. 这里我给出一个 org 文件的模板示例.

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


#+OPTIONS: author:nil ^:{}
#+HUGO_FRONT_MATTER_FORMAT: YAML
#+HUGO_BASE_DIR: ../
#+HUGO_SECTION: posts/2022/04
#+DATE: [2022-04-24 Sun 20:29]
#+HUGO_CUSTOM_FRONT_MATTER: :toc true
#+HUGO_AUTO_SET_LASTMOD: t
#+HUGO_TAGS: 标签1 标签2
#+HUGO_CATEGORIES: 类别
#+HUGO_DRAFT: false
#+TITLE: 我的第一篇博客

This is my first blog!

头部文件说明

OPTION: 这里我们在 config.toml 中如果已经配置了, 就可以把作者给关掉
HUGO_FRONT_MATTER_FORMAT: ox-hugo 将 org 文件中的头文件转换成 Markdown 文件的头部参数时的指定格式, 这里我们指定的是 YAML 格式
HUGO_BASE_DIR: 我们博客的根目录的位置, 这里我们的位置是上一层目录 ../
HUGO_SECTION: 生成 Markdown 文件的位置, 这里的路径是相对博客根目录下的 content 文件夹的, 所以我们这里生成的 Markdown 文件就去了 content/post/2022/04 这个文件夹下
HUGO_CUSTOM_FRONT_MATTER: Markdown 文件头部参数设置, 我们这里把目录 toc 打开
HUGO_AUTO_SET_LASTMOD: 最后修改时间, t 表示自动生成
HUGO_TAGS/CATEGORIES: 标签和类别
HUGO_DRAFT: 默认情况下所有文章和页面均作为草稿创建, 我们让文章立即可以渲染

这些头部文件难道需要我每次都手动输入? 不会的啦, 我们可以使用 Emacs 的模板工具 yasnippet 快速生成. 这里我分享下我的模板

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


# -*- mode: snippet -*-
# name: hugo_blog
# key: <hugo
# --
#+OPTIONS: author:nil ^:{}
#+hugo_front_matter_format: yaml
#+HUGO_BASE_DIR: ../
#+HUGO_SECTION: posts/`(format-time-string "%Y/%m")`
#+DATE: `(format-time-string "[%Y-%m-%d %a %H:%M]")`
#+HUGO_CUSTOM_FRONT_MATTER: :toc true
#+HUGO_AUTO_SET_LASTMOD: t
#+HUGO_TAGS: $1
#+HUGO_CATEGORIES: $2
#+HUGO_DRAFT: false
#+TITLE: $3

$0

使用 `Markdown` 创建你的第一篇文章

输入如下命令创建:

1

hugo new posts/我的第一篇文章.md

接下来我们用编辑器编辑这个文件就可以了, 也可以加上适当的头部参数, 下面是一个示范:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


---
title: "我的第一篇博客"
date: 2022-04-23T02:24:00+08:00
lastmod: 2022-04-24T21:00:18+08:00
tags: ["标签1", "标签2"]
categories: ["类别"]
draft: false
toc: true
---

This is my first blog!

第五步在本地预览你的网站

我们的文章写好了, 想看看最终渲染的效果如何, 我们可以先在本地启动网站:

1

hugo serve

如果渲染成功, 这时候命令行会返回一个预览网址, 复制到游览器打开即可预览你的文章.

一般为: http://localhost:1313

示意图如下:

第六步将你的博客部署到 Github

创建一个个人的 `Github Pages` 仓库

如下图所示, 要注意的就是仓库名要和你的 Github 用户名一致

构建博客网站

你准备好部署你的博客时, 运行一下命令:

1

hugo

会生成一个 public 目录, 其中包含你网站的所有静态内容和资源, 这个 public 目录就是你要部署到 Github 上的目录.

部署到 `Github`

切换到 public 目录下, 我们执行一些熟悉的 git 操作

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


# 将 public 目录初始化为一个 git 本地仓库
git init

# 将所有内容添加到本地仓库
git add .

# 提交到本地仓库
git commit -m "My blog's first commit"

# 关联到个人的远程仓库
git remote add origin <https://github.com/.../>

# 推送到远程的 git 仓库
git push origin main

其实远程第一次提交的时候, 远程仓库有一个默认的 README.md 文件, 本地是没有的, 我们可以先 git pull --rebase 一下再提交, 但是对于第一次提交, 由于没有什么有效文件, 其实强制提交 git push -f origin main 也是可以的

部署的过程有些繁琐, 我们可以写一个 Shell 脚本来简化一下我们的操作, 脚本 deploy.sh 如下:

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


#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# build the project
hugo

cd public

git add .

msg="rebuilding site `date`"

if [ $# -eq 1 ]
  then msg="$1"
fi

git commit -m "$msg"

# push source to github

git push upstream main

# come back to blog root

cd ..

执行脚本的话先更改一下权限再执行:

1
2
3
4


chmod 700 ./deploy.sh

# 执行脚本
./deploy.sh

在 Github 上等待 `Git Action` 完成, 访问你的博客

是的, 你把 public 上传后, 需要等待 Git Action 完成 Github pages 的构建.

之后访问你的 Github pages 网址即可看到你的博客啦.

这个网址是 https://your_github_name.github.io

结尾

可以考虑使用 DoIt 替代 LoveIt

如何用 hugo 和 org-mode 搭建个人博客

关于本文

用到的工具和操作流程

工具

操作流程

第一步 在 emacs 上安装 ox-hugo

关于 ox-hugo

安装 ox-hugo

普通安装

通过使用 use-package 来安装

在 doom-emacs 中安装

ox-hugo 的使用与配置

使用 ox-hugo

配置 ox-hugo

第二步 安装 hugo, 并做初始化

安装 hugo

初始化 hugo (创建一个新的网站)

第三步 安装一个自己喜欢的 hugo 主题(以 LoveIt 为例)

安装主题 LoveIt