使用 Hugo + Github Pages 創建靜態網站博客

最好的參考資料仍然是官方。本文僅作一個基本描述

安裝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

最關鍵的幾個文件/目錄:

  1. config.toml 配置文件,要定製化的東西幾乎全在這裏修改。

  2. themes 存放主題的目錄。裏面可以放一個或多個主題

  3. 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)

特點:

  1. 搜索很快
  2. 首頁和正文的間距都很大
  3. 博客無修改時間
  4. 分類與標籤的樣式是一樣的
  5. favicon圖標設置:放在hugo-theme-stack/static/img/目錄下,修改hugo-theme-stack/config.yaml,設置params.favicon/img/your-favicon.ico,注意是/img不是img
  6. 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 and docs. Our documentations uses the docs layout. If you're looking for an example that using posts layout, please take a look at Markdown Syntax.

——from:Docs Layout - Hugo Bootstrap (razonyang.com)

優點

  1. 頁面控件支持超寬佈局

  2. 代碼控件支持超長代碼摺疊

  3. Docs Layout 可以方便的將整個知識庫放上去,這樣本地的分類目錄就能直接給博客使用,博客無需關心分類、標籤的問題。

    image.png

LoveIt

dillonzq/LoveIt: ❤️A clean, elegant but advanced blog theme for Hugo 一個簡潔、優雅且高效的 Hugo 主題 (github.com)

搜索

LoveIt主題支持"lunr"和"algolia"兩種搜索:

lunr: 簡單,配置type = "lunr"即可。運行hugo會將生成的index.json索引文件放在public/目錄下,隨網站一起發佈。沒有 contentLength 的限制,但佔用帶寬大且性能低 (特別是中文需要一個較大的分詞依賴庫)。客戶端需將整個index.json從網站下載到本地,然後基於此文件進行搜索。下圖是使用lunr搜索時,生成的靜態文件,可見分詞庫有3.6MB:
image.png

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]塊。

使用本地資源

有三種方法來引用圖片音樂等本地資源:

  1. 使用頁面包中的頁面資源. 你可以使用適用於 Resources.GetMatch 的值或者直接使用相對於當前頁面目錄的文件路徑來引用頁面資源。所謂的頁面包,就是圖片和md文件放在一起(使用相對路徑訪問)。
  2. 將本地資源放在 assets 目錄中, 默認路徑是 /assets. 引用資源的文件路徑是相對於 assets 目錄的.
  3. 將本地資源放在 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
    ---
    

缺點

  1. 搜索沒有jekyll + chirpy的好,也沒有stack的開箱即用。(algolia要自己搞上傳,lunr分詞有問題)。

  2. 主題不太美觀

  3. 畫廊。使用以下語法。不加“圖片描述”不會激活。未使用畫廊的圖片,點擊不會響應,只能右鍵新標籤打開,放大查看。還有個小bug,頁面刷新後,圖變小了。

    ![image.png](https://cdn.jsdelivr.net/gh/whuwangyong/whuwangyong.github.io@gh-pages/2022-04-19-hugo/assets/image-20220329160821-l8rh3to.png "圖片描述")
    
  4. 最重要的,兩年沒維護了。但這個主題確實不錯,所有有不少人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”目錄下。
image.png
我的建議是不要這樣做。因爲分類是一個很難的事情,隨着時間推移大概率會動態調整。調整之後意味着之前發佈的博客的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個:

  1. date字段寫詳細:date: 2022-04-19T00:56:00+08:00
  2. 修改config.toml,添加一行配置,執行可以編譯未來的文章:buildfuture = true
  3. 使用hugo server --buildFuturehugo --buildFuture命令
  4. 修改config.toml,添加一行配置,指定時區:timezone = "Asia/Shanghai"

推薦採用方法(4)。


本文同步發佈於:

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章