安裝支援 asciidoc 語法的 hugo

install hugo asciidoctor - 2022-05-06

安裝 RVM → 安裝 ruby → 安裝 asciidoctor → 安裝 hugo

Why

用什麼工具產出靜態網頁其實不重要，重要的是支援轉換的格式。雖不重要但也不能效能太差，就選一個最新發展的。可惜，目前沒看到原生支援 AsciiDoc 的靜態網站產生器。還好 Hugo 可以使用外部轉換器，雖然結果不是很完美。那為什麼選 AsciiDoc 不選 Markdown？當然是因為 AsciiDoc 是 A 開頭，而 Markdown 是 M 開頭，兩個差距可不是一個兩個。哈 …，其實是 AsciiDoc 支援的格式多。

What

Hugo: Hugo 用 golang 寫的靜態網站產生器，內容格式原生支援 Markdown。
Markdown: Markdown 是一種輕量級標記式語言，以易於閱讀、易於撰寫的純文字格式為賣點，可轉換成 HTML。發展較早，早期支援的排版格式較少，後來演申出許多方言來加強。
AsciiDoc: AsciiDoc 是一種輕量級標記式語言，語法有點像 Markdown，可轉換成 HTML 或各種電子書格式。支援更多排版格式，語法較一致且考慮到出版需求。
Asciidoctor: Asciidoctor 以 Ruby 實現的 AsciiDoc 轉換工具實作。然後加了一堆他認為好用的特性。也是目前認為最好的 AsciiDoc 轉換工具。
Ruby: Ruby 一種 Script Language。
rbenv: rbenv 是安裝與管理 Ruby 版本的工具。
RVM: RVM 是安裝與管理 Ruby 版本的工具。
gem: gem 是 Ruby 的套件管理服務工具。

How

安裝 asciidoctor 必須有 ruby 環境，而 `ruby 可由 rbenv 或 `RVM 安裝。

安裝 asciidoctor

使用 RVM 安裝 asciidoctor && asciidoctor-diagram

> sudo apt install gnupg2 // (1)
> gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
> curl -sSL https://get.rvm.io | bash -s stable
> rvm install ruby-3
> gem install asciidoctor
> gem install asciidoctor-diagram // (2)

gnupg2 是自由軟體基金會版本的 PGP
asciidoctor 使用 asciidoctor-diagram 模組呼叫外部工具來完成繪圖

asciidoctor-diagram 呼叫外部工具，不同的繪圖格式要安裝相對應的工具，例如

graphviz sudo apt-get install -y graphviz
ditaa sudo apt-get install -y ditaa

安裝 Hugo

到下載 Hugo 選擇你要版本，複製你需要版本的連結。下載 → 解壓縮 → 複製到路徑。

e.q. 下載 Linux 64bit 版, 目前版本為 v0.98.0

> https://github.com/gohugoio/hugo/releases/download/v0.98.0/hugo_0.98.0_Linux-64bit.tar.gz
> tar zxvf hugo_0.98.0_Linux-64bit.tar.gz
> cp hugo /usr/local/bin/                 // (1)

複製執行檔到可執行路徑或將 hugo 執行檔所在目錄加到可執行路徑

config hugo

這個版本的 hugo 終於提供呼叫 asciidoctor 的參數配置方式。不用自己改寫 script，只要在設定檔中加入下列設定即可。

config.toml

[markup.asciidocext]
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
backend = "html5s"
trace = true

[markup.asciidocext.attributes]
data-uri = ""
allow-uri-read = ""
imagesdir="adg"

等同 asciidoctor -b html5s -r asciidoctor-html5s -r asciidoctor-diagram -a data-uri -a allow-uri-read -a imagesdir=adg --no-header-footer --trace -

但同時因為安全考量 hugo 要求必須設定安全相關的參數，可參考如下

config.toml

[security]
enableInlineShortcodes = false

[security.exec]
allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^asciidoctor$']  // (1)
osEnv = ['(?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM|GEM_PATH)$'] // (2)

[security.funcs]
getenv = ['^HUGO_']

[security.http]
methods = ['(?i)GET|POST']
urls = ['.*']

加入允許 asciidoctor 執行。
環境參數加入 GEM_PATH ，呼叫不到 ruby。

啟動 hugo server

hugo server -p <port> --bind=0.0.0.0 --baseURL=http://<ip or domain>/

--bind=0.0.0.0 是不綁定特定 IP ，內定是 127.0.0.1。當主機有多個 IP 介面時可以指定其中一個。不綁定特定 IP 適用主機本身沒有 Pubic IP 介面的雲端或內部主機。

--baseURL= 的設定會影響到 {{.Site.BaseURL}} 或 {{.Permalink}} 等會引用 baseURL 的參數值。若連結網址不要包含 baseURL 可將 {{.Permalink}} 改為 {{.RelPermalink}}。

P.S.

若 haed 上 date 屬性值大於現在時間，該文章不會被宣染。
若 haed 上 draft 屬性值設為 true 則該文章不會被宣染。