從頭教你使用 Hugo 搭建自己的博客

點擊上方藍色「Go語言中文網」關注我們，領全套Go資料，每天學習 Go 語言

本文作者：D瓜哥 

原文連結：https://www.diguage.com/post/building-blog-with-hugo/

一個朋友對D瓜哥的博客感興趣，覺得很好玩。問我怎麼玩，D瓜哥也懶得手把手教了，乾脆寫篇文章來做個說明吧。也許對其他朋友也有所幫助。

潮起潮落

D瓜哥早在 2012年就使用 WordPress 搭建了一個博客： "地瓜哥"博客網—分享技術帶來的喜悅，WordPress 不虧是全世界最流行的開源 CMS 系統，各種插件可以滿足非常對的需求。當年D瓜哥還想研究一下它的原始碼，可惜對 PHP（對，就是那個拍黃片的）無感，沒有堅持下去。

但是，在熟悉了 MarkDown、 Asciidoctor（D瓜哥是 AsciiDoctor 的死忠粉，堅決支持它的發展） 等輕量級標記語言後，愈發覺得 WordPress 太繁瑣：寫作一個小時，排版發布一小時。實在是太浪費時間了。

先嘗試了一下 Antora，之所以選它，是因為它是 AsciiDoctor 的作者發起的項目，對 AsciiDoctor 的支持性非常好。嘗試了一段時間後，發現它更適合寫產品說明書，更適合像阿里雲等這種對外提供產品，需要提供在線產品說明書的情況。不適合做個人博客。

去年，經過多次測試後（主要測試對 AsciiDoctor 的支持性），發現現在D瓜哥用的這個主題對 AsciiDoctor 支持得不錯，隨後下定決心切換到了 Hugo。

Hugo 簡介

關於 Hugo 的介紹，直接轉摘維基百科的介紹了：

Hugo 是一個用 Go 編寫的靜態網站生成器，2013由 Steve Francia 原創，自 v0.14 (2015年) 由 Bjørn Erik Pedersen 主力開發，並由全球各地的開發者和用戶提交貢獻。Hugo 以 Apache License 2.0 許可的開放原始碼項目。

Hugo 一般只需幾秒鐘就能生成一個網站（每頁少於 1 毫秒），被稱為「世界上最快的網站構建框架」，也使 Hugo 大受歡迎，成為最熱門的靜態網站生成器之一，被廣泛採用。例如，2015年7月，Netlify 推出專為 Hugo 而設的網站託管服務，而2017年，Smashing Magazine 推出重新設計的官方網站，從原來的 WordPress 遷移到基於 Hugo 的 JAMstack 解決方案。

— https://zh.wikipedia.org/wiki/Hugo_(軟體)

Hugo 確實非常快，Kubernetes 的官網以及文檔就是使用 Hugo 生成的，那麼龐大的文檔，在本地預覽是，啟動伺服器也非常快。

D瓜哥在查資料時，遇到從 Hexo 切換到 Hugo 的案例，主要原因就是 Hugo 的速度驚人。我們就直接上 Hugo 了。

安裝

關於安裝，直接使用 Hugo 的官方文檔可以參考 Install Hugo，這裡做個概要翻譯：

Mac

在 Mac 下安裝 Hugo 非常簡單，使用 Homebrew 只需要下面這一條命令即可：

brew install hugo

Tip

不了解 Homebrew 的，可以點擊上面的連結，自行了解。Linux

Linux 也支持 Homebrew 了，可喜可賀，上面的命令可以復用了：

brew install hugo

Windows

Windows 安裝，可以使用 Chocolatey - The package manager for Windows，也非常簡單，一條命令：

choco install hugo -confirm

// 如果需要支持 Sass/SCSS，可以使用擴展版
choco install hugo-extended -confirm

創建網站

安裝完成後，就會有一條命令行工具 hugo，後續操作大部分都需要這條命令參與。

新建站點

新建站點非常簡單，也是一條命令行：

hugo new site diguage.com # diguage.com 這個名字可以隨意取，它其實就是一個文件夾名。

上述命令會生成一個名為 diguage.com 的文件夾，下面對文件夾結構做個說明：

$ tree diguage.com
diguage.com
├── archetypes
│   └── default.md
├── config.toml # 配置文件
├── content # 以後的文章就放在這個目錄下
├── data
├── layouts
├── static # 這裡存放靜態資源文件，比如 CSS、JS 以及圖片
└── themes # 這裡存放主題

新建的站點，還沒有加入 Git 版本管理，進入到這個目錄下，執行一下如下命令，完成 Git Repo 的初始化：

git init . # 這步做不做都可以，但是推薦將博客放在 GitHub 或者 Gitee 上，更安全

新建站點後，我們開始添加主題。

添加主題

在 Hugo 的官網上 Hugo Themes 有非常非常多的主題，可以根據自己的喜好選擇一個主題。

Hugo Theme Jane 是D瓜哥比較中意的一款主題，而且是由國人開發的，對中文支持也非常好。這裡就選它作為示例來演示。

每個主題頁面都有按照介紹，直接按照安裝介紹來操作就好。

git clone https://github.com/xianmin/hugo-theme-jane.git --depth=1 themes/jane

克隆完成後，使用如下命令完成配置：

# 將示例內容拷貝到新建站點中
cp -r themes/jane/exampleSite/content ./

# 將默認配置拷貝到新建站點的配置中
cp themes/jane/exampleSite/config.toml ./

然後啟動預覽：

hugo server

默認是 1313 埠號，在瀏覽器中直接訪問 http://localhost:1314/ 就可以訪問到新建的博客了。

根據自己的需要，修改根目錄下的 config.toml 文件，來修改自己站點的配置。

附加工具推薦輕量級標記語言

使用 Hugo 搭配輕量級標記語言才是絕配！輕量級標記語言在增加稍許複雜性的情況下，可以大大提高文檔的美觀性和可讀性。所以，可樂而不為？

這裡，推薦兩款輕量級標記語言。

AsciiDoctor

首先，推薦的是 Asciidoctor。本網站的所有文檔都是使用 AsciiDoctor 格式來書寫的。

Asciidoctor 是一套處理 AsciiDoc 的完整工具鏈。同時，還提供了非常完善的文檔。這樣，幾乎可以一站式解決常見問題，而不用找各種插件來搭積木。

AsciiDoctor 在比 MarkDown 複雜度上增加了一點點，但是功能卻強大好多好多倍！如果說 MarkDown 是出版界的小學生，那麼 AsciiDoctor 就是出版界的大學畢業生。（在 GitHub 上讀到的一句話，原文找不到了。）O』Reilly 就基於 AsciiDoctor 開發了在線圖書編輯系統。

常用的文檔有這麼幾個：

AsciiDoc Syntax Quick Reference — 這是一個入門文檔。常見的功能基本都可以找到說明介紹。如果想玩高級功能，可以去下面文檔查找。

Asciidoctor User Manual — 這是 AsciiDoctor 的完整文檔，五花八門的功能介紹都可以找到。找不到可以去 GitHub 上提 Issue，如果用英文，一般一天之內就會有人回復的。

AsciiDoctor Diagram — 需要圖表支持的，這裡提供了豐富的圖表集成。

AsciiDoctor PDF — 想要直接轉化成 PDF，沒問題，這個工具就能幫你搞定！

MarkDown

坦白講，MarkDown 是D瓜哥最早接觸的輕量級標記語言。也是目前使用最廣泛的輕量級標記語言。GitHub，Gitlab 以及很多工具都有完善地支持！

MarkDown 也是 Hugo 原生支持的標記語言，渲染速度非常快。同時，還支持很多簡碼（shortcode）。如果第一次接觸，為了省去不必要的麻煩，建議從 MarkDown 玩起。

但是，MarkDown 美中不足的是，它沒有標準化，有非常多的方言和擴展。這裡給幾個比較

Markdown Guide: Basic Syntax — 這是一個可讀性非常好的 MarkDown 教程，可以從這裡開始。

Markdown Tutorial — 這是一個交互教程。

GitHub Flavored Markdown Spec — GitHub 改進過的 MarkDown，玩 GitHub 必備。

Syntax | Mmark: powerful markdown parser — 這是 hugo 支持的 MarkDown 格式。做個作為備查，或者你想玩高級玩法的時候的一個參考資料。

上面給的文檔很多，找一個自己感興趣的，通讀下來，各種語法實驗一遍，學會就行。不必全部通讀。

主題推薦

Hugo 的主題特別特別多，這裡推薦兩款私以為比較漂亮的主題：

Jane

Hugo Theme Jane 應該是國人開發的一個主題。對中文支持得比較好，整體頁面也簡潔大方，乾淨利落。並且響應性和移動友好性也都特別棒。

Figure 1. Hugo Theme Jane

Mainroad

Hugo Themes Mainroad 是我目前正在使用的主題，通過添加 CSS 可以很好的支持 AsciiDoctor。美中不足的是，它原生不支持「歸檔」頁面。等有機會，D瓜哥把自己改造後的主題發布出來。

Figure 2. Hugo Theme Mainroad

VS Code 插件

hugofy 是 VS Code 下的一個插件，可以方便我們創建文章，非常方便，推薦。

自動發布

D瓜哥推薦把博客的 Repo 放在 GitHub 上，使用 GitHub Action 可以非常方便地發布到 GitHub Pages，簡直爽得不要不要的。

Figure 3. Hugo to GH Pages

Hugo to GH Pages 就是這樣一個 GitHub Action 插件。大家可以嘗試一下。

大家還有什麼問題，歡迎留言討論……

參考資料

Hugo to GH Pages · Actions · GitHub Marketplace

推薦閱讀

站長 polarisxu

自己的原創文章

不限於 Go 技術

職場和創業經驗

Go語言中文網

每天為你

分享 Go 知識

Go愛好者值得關注