安裝支援 asciidoc 語法的 hugo

install hugo asciidoctor - 2018-03-12

安裝 asciidoctor → 安裝 hugo

Why

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

What

Markdown: Markdown 是一種輕量級標記式語言，以易於閱讀、易於撰寫的純文字格式為賣點，可轉換成 HTML。
AsciiDoc: AsciiDoc 是一種輕量級標記式語言，語法有點像 Markdown，以人類易於閱讀、易於撰寫的純文字格式為賣點，可轉換成 HTML 或各種電子書格式。
Asciidoctor: Asciidoctor 以 Ruby 實現的 AsciiDoc 轉換工具實作。然後加了一堆他認為好用的特性。也是目前認為最好的 AsciiDoc 轉換工具。
Ruby: Ruby 一種 script language。
rbenv: rbenv 是安裝與管理 Ruby 版本的工具。
gem: gem 是 Ruby 的套件管理服務工具。
Hugo: Hugo 用 golang 寫的靜態網站產生器，內容格式原生支援 Markdown。

How

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

安裝 rbenv

如果沒有 Ruby 執行環境，請先安裝 rbenv。

> git clone https://github.com/rbenv/rbenv.git ~/.rbenv         // (1)
> cd ~/.rbenv && src/configure && make -C src                   // (2)
> echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc      // (3)
> echo 'eval "$(rbenv init -)"' >> ~/.bashrc                    // (4)

從 github 複製 rbenv 原始碼到安裝目錄 ~/.rbenv
切換到安裝目錄並編譯
將結果設到可執行路徑
在啟動時載入 rbenv

從新載入 shell 或 source ~/.bashrc 後，將 ruby-build 安裝為 rbenv 的 plugin。

安裝 ruby-build && ruby

> mkdir -p "$(rbenv root)"/plugins                              // (1)
> git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build // (2)
> sudo apt-get install -y libreadline-dev                       // (3)
> RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.5.0 // (4)

建立 rbenv plugins 目錄
從 github 複製 ruby-build 原始碼到 plugins 目錄
安裝 libreadline-dev 函式庫來避免 The Ruby readline extension was not compiled. 編譯錯誤
安裝並編譯你要的 Ruby 版本，使用 RUBY_CONFIGURE_OPTS=--disable-install-doc 參數來禁止編譯 rdoc 可避免一些編譯錯誤

最後，使用 curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash 來檢測安裝結果

沒問題，就可以使用 rbenv global 2.5.0 將要使用的 Ruby 版本設給 rbenv

安裝 asciidoctor && asciidoctor-diagram

> gem install asciidoctor
> gem install asciidoctor-diagram

但 asciidoctor-diagram 依賴呼叫外部工具來完成繪圖，用不同的繪圖格式就要安裝相對應的工具，例如

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

安裝 Hugo

到下載 Hugo 選擇你要版本

e.q.

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

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

要啟動 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}}。

fix asciidoctor

現在你應該可以利用 hugo 將 ad 轉成 html，但基於 Hugo Supported Content Formats 傳給 asciidoctor 的參數是 asciidoctor: --no-header-footer --safe --trace - 沒有載入 asciidoctor-diagram 模組，所以做圖是沒有作用的。

要改傳參數給 asciidoctor 可以修改 vi $(which asciidoctor) 來達成。因為 hugo 呼叫 getAsciidoctorExecPath() 來取得 asciidoctor 的執行路徑，約同於 which asciidoctor，但如果你使用 rbenv 安裝 ruby 他會使用 'shims' 來執行，而每次使用 eval "$(rbenv init -)" 載入 rbenv， shims 上的執行檔就會被覆寫。

所以將修改後的 asciidoctor 另存路徑並將該路徑設給 PATH，讓 hugo 執行你改寫的 asciidoctor，即可。

asciidoctor

#!/usr/bin/env bash
set -e
[ -n "$RBENV_DEBUG" ] && set -x

program="${0##*/}"
if [ "$program" = "ruby" ]; then
  for arg; do
    case "$arg" in
    -e* | -- ) break ;;
    */* )
      if [ -f "$arg" ]; then
        export RBENV_DIR="${arg%/*}"
        break
      fi
      ;;
    esac
  done
fi

export RBENV_ROOT="/home/robin/.rbenv"
#exec "/home/robin/.rbenv/libexec/rbenv" exec "$program" "$@"
# fix to
exec "/home/robin/.rbenv/libexec/rbenv" exec "$program" \
"-r" "asciidoctor-diagram" \            // (1)
"-B" "/tmp" \                           // (2)
"-a" "imagesdir=adg/$(date +%s)" \      // (3)
"-a" "data-uri" \                       // (4)
"-a" "allow-uri-read" \
"$@"

使用 -r asciidoctor-diagram 載入 sciidoctor-diagram，參 https://asciidoctor.org/docs/asciidoctor-diagram/
設定 base_dir 以避開在工作目錄產生的各種中間產物
設定 imagesdir 在時戳目錄下以避開同名圖檔
使用 -a data-uri -a allow-uri-read 將圖片嵌入 html，參 https://asciidoctor.org/docs/convert-documents/