使用 hugo 的 Material for Hugo 樣板紀錄


Hugo 是 go 語言寫的 Static Web Generator,認真說起來也不是很新,已經有一段時間了。目前在 site generator 的星星熱門程度大約是 9000 多個星,如果你想要參考一下其他的 site generator 可以看: https://www.staticgen.com/,這裏有列出很多的 site generator~

site generator 我用過 Jekyllsculpin,jekyll 是 gem; sculpin 是用 php,不過現在大部份的 site generator 背後是什麼程式語言在驅動,好像也沒什麼差別,因為需求導向,我需要一個可以拿來寫 User Guide 的 site generator,只是湊巧遇到 hugo 有這個不錯的樣版,就打算來使用看看。


時間壓力,我認為直接使用現成的 theme 的結構跟 example,參考其檔案目錄直接換成自己要的內下,是比較快速的方法 :p (<- 沒時間還有空寫文章?!)

以下是假設你要使用 hugo 會造訪的主要三個網頁
* Hugo 官網: http://gohugo.io/
* hugo Github: https://github.com/spf13/hugo
* Hugo 的樣板: http://themes.gohugo.io/

關於 HUGO 的基本介紹
* 快速,有多快? 詳見 https://youtu.be/CdiDYZ51a2o
* 跨平台 (Max OS X, Linux, windows)
* LiveReload!
Pretty URL Support, Aliases (其實就是 redirect), tags 支援, category 支援, 客製化 URLs, Permalink  pattern support.
* 內容支援 Markdown
Front Matter 支援 TOML, YAML, JSON 等的 format, 如 TOML 檔的話,是 +++, YAML 的話是 ---。
* 有 wordcount, minutes to read 功能(主要還是吃 pgae variable 的設定,如 ReadingTime)。
* 其他支援如 Disqus 整合, Google Analytics, RSS... 等等。
* Syntax 支援 highlighting (Pygments)。

不只這些,我只寫了幾項我覺得重要的。

Migration 工具:
有些 tool 可以幫助你從別家跳到 Hugo 的工具,如 JekyllToHugo, Blogger To Hugo(blogimport), wordpress-to-hugo-exporter, octohug...,見 https://gohugo.io/tools/


安裝 HUGO
我這篇不介紹 hugo 怎麼用的細節(細節用介紹是沒有用的,下去修修改改一個 static stie 才有感覺 XD),只是拿一個樣板來介紹 git clone 跟起 server 的方式。 當然首先你的電腦要有 安裝 go,然後再安裝 hugo。這裏不介紹安裝 go,但 hugo 下載請使用 homebrew:

brew update && brew install hugo


安裝完之後,hugo 的安裝是 global 的,也就是哪裡都能執行這個指令,你可以下 hugo version 用來確認 hugo 的版本:

windeMacBook-Air$ hugo version
Hugo Static Site Generator v0.15 BuildDate: 2015-11-26T14:29:00+08:00
當版本號完整呈現時,就先當作他裝好了。或是你也可以下 hugo help 確認 hugo 存在。


Hugo-material-docs 樣板
接著我要使用的樣板是 https://github.com/digitalcraftsman/hugo-material-docs,你可以照著我寫的步驟,也可以以官方網站的為主,以下步驟給大家參考:

到 https://digitalcraftsman.github.io/hugo-material-docs/,按下左邊的 Download 之後,你會下載 hugo-material-docs-master.zip (預設是抓下 master 這個 branch),解壓縮後,用編輯器開啟這個 folder。

這是目前的 folder 結構

接下來作者很有心地提供了頁面的 sample 給你,你會發現有個 exampleSite 資料夾,首先進入到 exampleSite 把 content 資料夾以及 config.toml 複製出來到根目錄下。

(exampleSite 裡面還有個 static 資料夾,請忽略他,暫時無必要選擇它...)



複製出來之後的跟目錄結構 (也就是多了 config.toml, content資料夾)

接著請打開 config.toml 檔案(注意不要開到 exampleSite 裡面的那個 config.toml,現在要開的是根目錄下面的 config.toml)。

把第四行的 theme 改成空值,這個 theme 的參數的目的在於去尋找 themes/THEMENAME 資下夾下的 theme,但我下載的時候已經是 theme/THEMENAME 的目錄下了,所以就把她留空。 (或是你想要走留下 themes/XXXX 的那種檔案結構的開發方式,請你參考 https://digitalcraftsman.github.io/hugo-material-docs/getting-started/)


接下來起 server 只需要在根目錄下 hugo server,預設會佔用 1313 PORT,如:

造訪 localhost:1313 如果畫面正常,你也可以把 exampleSite 整個資料夾刪掉了。



一些我應該要提到的事
1. hugo server 本身就有 watch (LiveReload) 的功能,所以你如果改了 md, 會重新 gen!
2. 使用 hugo 未必一定要從   theme 下手,你也可以自己 scaffold  一個全新的乾淨的 hugo site。指令大概是類似 hugo new site myblog

全新的目錄結構:

預設的 folder 都有其意義,請參考 https://gohugo.io/overview/quickstart/ Getting Started -> Quickstart 的地方。

3. hugo 的功能真的很多,你可以慢慢摸索!

留言

這個網誌中的熱門文章

[Android] 筆記 手機上測試自己的 APP

解決fatal: Not a git repository (or any of the parent directories): .git錯誤

[Android 筆記] 設定 ImageView 的圖檔來源