最好的參考資料仍然是官方。本文僅作一個基本描述
安裝Hugo
在此處下載安裝包。有兩個版本:(1)hugo;(2)hugo_extended。怎麼選?很多功能,包括一些主題,都需要hugo_extended的支持,因此,建議安裝hugo_extended。下載之後,解壓,將hugo.exe加入環境變量即可。
創建站點
僅需一個命令:
> hugo new site my_blog
站點的目錄結構如下:
> ls my_blog
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 2022/4/16 16:32 archetypes
d----- 2022/4/16 16:32 content
d----- 2022/4/16 16:32 data
d----- 2022/4/16 16:32 layouts
d----- 2022/4/16 16:32 static
d----- 2022/4/16 16:32 themes
-a---- 2022/4/16 16:32 82 config.toml
最關鍵的幾個文件/目錄:
-
config.toml 配置文件,要定製化的東西幾乎全在這裏修改。
-
themes 存放主題的目錄。裏面可以放一個或多個主題
-
content 存放博客的目錄。後續以markdown格式寫的文章,就放在這下面:
content/ └── posts/ └── this-is-my-first-blog/ <-- page bundle | ├── index.md | └── sunset.jpg <-- page resource └—— this-is-my-second-blog.md
注意,如果將md文件和引用的圖片放在一個文件夾下(官方叫
page bundle
),則md文件需命令爲index.md,否則md在渲染爲html後,裏面的圖片不會顯示。
添加主題
新建的站點是空的,需要添加一個主題後才能正常使用。此處以FixIt主題爲例。關於主題的選擇,請看下一節主題推薦。
添加主題有兩種方式:
(1)將主題下載下來,放在themes目錄下即可
(2)將主題以子模塊的形式添加到站點,使用git管理。這麼做主要是便於以後升級。本文采用此方式。關於git submodule的更多信息查看這裏:git submodule - 標籤 - 武大路飛 (whuwangyong.github.io)
另外,建議不要直接修改主題裏面的文件,以後升級時合併起來很麻煩。沒什麼問題,主題可以一直使用,沒必要頻繁升級。
> cd my_blog
> git init
> git submodule add https://github.com/Lruihao/FixIt.git themes/FixIt
# 以後可以使用以下命令升級主題
> git submodule update --remote --merge
主題推薦
官網提供了很多主題,我試用了一些,從以下幾個角度進行選擇:
最後選出了以下幾個。
Stack
Stack | Hugo Themes (gohugo.io)
特點:
- 搜索很快
- 首頁和正文的間距都很大
- 博客無修改時間
- 分類與標籤的樣式是一樣的
- favicon圖標設置:放在
hugo-theme-stack/static/img/
目錄下,修改hugo-theme-stack/config.yaml
,設置params.favicon
爲/img/your-favicon.ico
,注意是/img
不是img
- md圖片目錄不能以 · 開始。否則渲染之後圖片src="/"是從根路徑開始的,就找不到圖片
Bootstrap
Bootstrap Theme for Personal Blog and Documentations | Hugo Themes (gohugo.io)
這個主題的特點是,默認採用的posts layout
,這個佈局下面的文章,側邊欄的TOC
目錄是不固定的。如果需要固定,請使用docs layout
。
This theme provides several kinds of layouts, such as
posts
anddocs
. Our documentations uses thedocs
layout. If you're looking for an example that usingposts
layout, please take a look at Markdown Syntax.
優點
-
頁面控件支持超寬佈局
-
代碼控件支持超長代碼摺疊
-
Docs Layout 可以方便的將整個知識庫放上去,這樣本地的分類目錄就能直接給博客使用,博客無需關心分類、標籤的問題。
LoveIt
搜索
LoveIt主題支持"lunr"和"algolia"兩種搜索:
lunr: 簡單,配置type = "lunr"
即可。運行hugo會將生成的index.json
索引文件放在public/
目錄下,隨網站一起發佈。沒有 contentLength
的限制,但佔用帶寬大且性能低 (特別是中文需要一個較大的分詞依賴庫)。客戶端需將整個index.json
從網站下載到本地,然後基於此文件進行搜索。下圖是使用lunr搜索時,生成的靜態文件,可見分詞庫有3.6MB:
algolia:高性能並且佔用帶寬低,但需要將 index.json
上傳到algolia官網(手動或使用Algolia Atomic腳本);有 contentLength
的限制。對於免費用戶:Your first 10,000 records are free, and every month you’ll receive 10,000 requests for our Search and Recommend products.
經過測試,lunr導致網站加載速度變慢,且搜索效果很不理想。所以我選擇了algolia。配置如下:注意 index = "new-index-1649076215"
,後面的值是你在algolia網站上創建的索引名。
[params.search]
enable = true
# 搜索引擎的類型 ("lunr", "algolia")
type = "algolia"
# 文章內容最長索引長度
contentLength = 4000
# 搜索框的佔位提示語
placeholder = ""
# 最大結果數目
maxResultLength = 10
# 結果內容片段長度
snippetLength = 50
# 搜索結果中高亮部分的 HTML 標籤
highlightTag = "em"
# 是否在搜索索引中使用基於 baseURL 的絕對路徑
absoluteURL = false
[params.search.algolia]
# 這裏填寫你在algolia上面創建的索引名
index = "new-index-1649076215"
appID = "YMLXXXXFHL"
searchKey = "9028b251fe4eexxxxxxxxxxxxx5a4f0"
多語言
所有寫在[languages]
外面的,都是所有語言公用的。Multilingual Mode | Hugo (gohugo.io)。我去故意掉了多語言,只保留了中文:將[languages.zh-cn]
下面的所有配置挪到外面,然後刪除空的[languages]
塊。
使用本地資源
有三種方法來引用圖片和音樂等本地資源:
- 使用頁面包中的頁面資源. 你可以使用適用於
Resources.GetMatch
的值或者直接使用相對於當前頁面目錄的文件路徑來引用頁面資源。所謂的頁面包,就是圖片和md文件放在一起(使用相對路徑訪問)。- 將本地資源放在 assets 目錄中, 默認路徑是
/assets
. 引用資源的文件路徑是相對於 assets 目錄的.- 將本地資源放在 static 目錄中, 默認路徑是
/static
. 引用資源的文件路徑是相對於 static 目錄的.引用的優先級符合以上的順序.
在這個主題中的很多地方可以使用上面的本地資源引用, 例如 鏈接 , 圖片 ,
image
shortcode,music
shortcode 和前置參數中的部分參數.頁面資源或者 assets 目錄中的圖片處理會在未來的版本中得到支持. 非常酷的功能!
Front Matter
https://hugoloveit.com/zh-cn/theme-documentation-content/#front-matter
轉義字符
https://hugoloveit.com/zh-cn/theme-documentation-content/#escape-character
SRI
啓用之後在github.io有問題:
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/lib/lunr/lunr.stemmer.support.min.d73a55668c9df0f2cbb2b14c7d57d14b50f71837e9d511144b75347e84c12ff8.js' with computed SHA-256 integrity 'EVRhgSylsJP5vMLxXSaTpskOj+ONq/I3Xl8Y4cNI2Xw='. The resource has been blocked.
whuwangyong.github.io/:1
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/lib/lunr/lunr.zh.min.e9abb2f5c7c0f738290cd8a5ff2ce1cf5deac6942f44ce5dd89c9ab1ae27006a.js' with computed SHA-256 integrity 's6qyS9abdG0o9DP0qC7PoVVqdbpe+fTKorzHq40yfBQ='. The resource has been blocked.
whuwangyong.github.io/:1
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/js/theme.min.09729ab43fbb7b49c065c597d41bb70983c7852ea77794a00b8f78099b049b43.js' with computed SHA-256 integrity '9Rk48wZaQO6EG8tVjkMw4x/SbA6lU0P/+HcLiLAxmjw='. The resource has been blocked.
頁面現象就是側邊欄目錄、評論都不顯示。但是在vercel.app沒問題。另外,console還有個warning:Error with Permissions-Policy header: Unrecognized feature: 'interest-cohort'.
LoveIt 總結
優點
-
文檔很詳細
-
默認在新標籤頁打開鏈接
-
可以設置代碼超過n行摺疊
-
標題加粗,更加清晰
-
使用 weight 置頂
--- weight: 1 # 置頂 title: "主題文檔 - 基本概念" date: 2020-03-06T21:40:32+08:00 lastmod: 2020-03-06T21:40:32+08:00 draft: false author: "Dillon" authorLink: "https://dillonzq.com" description: "探索 Hugo - LoveIt 主題的全部內容和背後的核心概念." resources: - name: "featured-image" src: "featured-image.jpg" tags: ["installation", "configuration"] categories: ["documentation"] lightgallery: true toc: auto: false ---
缺點
-
搜索沒有jekyll + chirpy的好,也沒有stack的開箱即用。(
algolia
要自己搞上傳,lunr
分詞有問題)。 -
主題不太美觀
-
畫廊。使用以下語法。不加“圖片描述”不會激活。未使用畫廊的圖片,點擊不會響應,只能右鍵新標籤打開,放大查看。還有個小bug,頁面刷新後,圖變小了。
![image.png](https://cdn.jsdelivr.net/gh/whuwangyong/whuwangyong.github.io@gh-pages/2022-04-19-hugo/assets/image-20220329160821-l8rh3to.png "圖片描述")
-
最重要的,兩年沒維護了。但這個主題確實不錯,所有有不少人fork了一份繼續維護。我選擇的是Lruihao/FixIt。
FixIt
Lruihao/FixIt: 🔧 A clean, elegant but advanced blog theme for Hugo 一個簡潔、優雅且高效的 Hugo 主題 (github.com)
它的原型基於 LoveIt 主題, LeaveIt 主題 和 KeepIt 主題。
LoveIt 主題 對我們來說是一個很棒的 Hugo 主題,很抱歉的是它的存儲庫已經停止維護很長一段時間了,所以我重建了一個名爲 FixIt 的新主題,這樣我可以更好地 Fix It 並使它用戶體驗更好。
- 修改了高亮顏色,比LoveIt更素雅好看一些。LoveIt的橙色行內代碼太花了
- 可以更便捷的修改頁面寬度,LoveIt的頁面略窄
- 但是,圖片刷新之後變小的bug還沒解決
- 幾乎可以從LoveIt無縫遷移
其他的就去看官方文檔吧。
Echo
https://github.com/forecho/hugo-theme-echo
這個主題未體驗,看了下覺得還不錯,也列在這裏吧。主要是到後面不想再折騰了……
關於主題選擇的總結
我最後的選擇是FixIt——LoveIt的繼續維護版。
其實我最喜歡的主題是 Chirpy,但這是 Jekyll 的主題。而Jekyll 使用的 Kramdown有問題,我做了很多嘗試也無法解決,所以放棄了 Jekyll, 轉 Hugo。
沒有完美的主題,選擇一個基本滿足要求的即可。比起不斷折騰主題,抓緊時間學習並輸出優質內容更重要。另外,如果正在使用的主題有什麼缺陷,首先應該仔細閱讀官方文檔和issue列表,尋找解決方案(這是一種能力),而不是立即去找一個新的主題代替它。因爲,可能在換了主題之後,我發現新的主題在其他地方也有缺陷,最終落入“主題大師”的陷阱——在N個主題裏面反覆橫跳,流於表面,沒有任何定製或者解決問題的能力。
運行示例站點
添加主題後,主題一般都帶有示例站點,在exampleSite目錄下。將exampleSite目錄下的所有文件拷貝到站點目錄下(my_blog)。然後使用如下命令啓動:
hugo server
訪問localhost:1313
即可查看效果。
如果報錯“Twitter timeout”之類的,是因爲示例站點裏面有些shortcode會連接twitter/YouTube之類的東西,國內連不上。刪掉相應文件即可。
自定義配置
配置文件是config.toml或config.yaml,有詳細註釋。另外,演示站點一般也是主題的說明文檔,有不明白的配置項,可以在演示站點上查閱,很方便。
新建文章
直接在content/posts
目錄下新建xxx.md即可。或者使用page bundle
模式,將index.md和引用的圖片放在同一文件夾。
也可以使用hugo new posts
命令新建,posts
來源於主題提供的模板。如FixIt主題提供了以下模板:
> ls .\themes\FixIt\archetypes\
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 2022/4/14 21:02 post-bundle
-a---- 2022/4/14 21:02 151 default.md
-a---- 2022/4/14 21:02 1044 friends.md
-a---- 2022/4/14 21:02 179 offline.md
-a---- 2022/4/14 21:02 633 posts.md
渲染
在站點目錄下運行hugo
命令即可。渲染之後的靜態文件位於public目錄下。將該目錄下的所有文件放在一個http服務器下面,即可提供服務。比如,在public目錄下,使用python命令運行一個http服務器:
> python -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...
然後瀏覽器訪問localhost:8000
即查看該站點。
發佈到github pages
將上述渲染的結果——public目錄下的所有文件,提交到username.github.io
這個repo,即可發佈到github pages。
進階內容
發佈到netlify、vercel
netlify、vercel 支持編譯hugo源文件。因此,你可以直接提交my_blog下面的hugo源文件(包括你寫的md文件、hugo相關的配置、主題文件等等,不包括渲染後的public/和渲染時生成的resources/)到github的一個repo,然後將該repo關聯到netlify、vercel,它們將會自動渲染併發布到它們的網站下。本站有相關文章,可以查看netlify、vercel標籤。
腳本化處理
我寫了一個python腳本來做渲染、發佈等事情,供參考。
提交到Google/百度/Bing等搜索引擎
可以使用在config.toml中填寫對應的配置;也可以將Google/百度等提供的驗證html文件放在站點的static目錄下。渲染後,這些驗證html文件會出現在public/目錄下。public/發佈之後,它們就位於網站的根目錄了,搜索引擎來抓取的時候就可以驗證。
同樣位於根目錄的還有sitemap.xml
,這是網站地圖,便於搜索引起爬取內容。另外,百度/Bing還提供了提交url地址的api。當你發佈新文章後,可以手動或寫腳本將url提交到搜索引擎,使文章更快地被收錄。
Tips
文章需要通過文件夾進行分類嗎
在寫了一些文章後,自然誕生出分類的想法。比如建站相關的,放在“建站”文件夾下;kafka相關的,放在“kafka”目錄下。
我的建議是不要這樣做。因爲分類是一個很難的事情,隨着時間推移大概率會動態調整。調整之後意味着之前發佈的博客的url失效。這對於SEO是很不利的,好不容易有個用戶搜到了你的博客,一點進來卻是404。
類似的,posts目錄下的文件名、目錄名,一經發布就不要改動。文章的標題和分類可以通過Front Matter修改:
---
title: "使用Jekyll + Github Pages搭建靜態網站"
date: 2022-03-29
tags: ["jekyll", "kramdown", "github pages"]
categories: ["靜態網站博客"]
---
hugo時區問題導致文章未顯示
比如現在時間是2022-04-19 0:56,我要發一篇文章,Front Matter寫爲:
---
title: "使用 Hugo + Github Pages 創建靜態網站博客"
date: 2022-04-19
tags: ["hugo"]
---
date字段我一般只寫日期,不寫時間。好,現在問題來了,hugo server一把,發現該文章未顯示。這是因爲hugo默認時區比中國時間慢8小時,當前還是4月18日。解決辦法有4個:
- 將
date
字段寫詳細:date: 2022-04-19T00:56:00+08:00
- 修改
config.toml
,添加一行配置,執行可以編譯未來的文章:buildfuture = true
- 使用
hugo server --buildFuture
或hugo --buildFuture
命令 - 修改
config.toml
,添加一行配置,指定時區:timezone = "Asia/Shanghai"
推薦採用方法(4)。
本文同步發佈於: