Hugo で AsciiDoc 原稿を書く際の留意点

Hugo は静的にWebサイトを生成するプログラムです．データベースを使って動的にページを生成するCMSと違い，ローカルに作成された全原稿から予めサイト全体のページを生成します．カテゴリやタグのページも静的に生成されます．このサイトも Hugo で作成しています．

原稿ファイルをHTMLに変換するのは Hugo ではなく Hugo が起動する外部プログラムです． Supported Content Formats にサポートする原稿のフォーマットが載っています．拡張されたMarkdownと AsciiDoc はデフォルトでサポートされており，変換プログラムとして Asciidoctor か AsciiDoc をインストールしパスを通しておけば，特に何の設定も必要なく .adoc 拡張子のファイルが変換されます．

ここでは， Hugo で AsciiDoc 原稿を書く際に，気付いた点をまとめておきます．インストールしている処理系は Asciidoctor であることを前提にしています．質問等ありましたら，ページ下のコメントか， @waterloo_jp までお願いします．

原稿のテンプレート

Hugo の原稿は content ディレクトリ内に作成します．エディタで直接ファイルを作成しても全く問題ありませんが，hugo new コマンドで作成すると archetype ディレクトリにある雛形のファイルをコピーして作成してくれます． AsciiDoc 用の雛形は archetypes/default.adoc に作成します．私の雛形は次のようになっています．

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
aliases:
categories:
tags:
comments: false
description: ""
keywords:
isCJKLanguage: true
---

= タイトル

== セクション

例えば，comp/hugo.adoc というパスのページを作成するには，

hugo new comp/hugo.adoc

を実行します．これで上の雛形の内容のファイルが content/comp/hugo.adoc に作成されます．

Level 0のタイトル

Hugo は = で始まるLevel 0のタイトルを無視します．独立した文書として変換するときのために = で始まる行にタイトルを記述しても問題ありません．ただし Hugo （もしくはtheme）がページタイトルとして抽出するのは，ページ冒頭の Front Matter 内で設定する title です．

コマンドの前後の空白

AsciiDoc は， DocBook に比べマークアップの手間が省ける分，地のテキストとコマンドを分離するマークアップ記号がありません．そのため，コマンドの前後に空白を置かなければならないという制約があります．

マークアップの前後のスペースに関する新しい投稿があります．「AsciiDoc で日本語原稿を書く際の留意点」

インライン・コードのケース

例えばインライン・コードを書くときには，下のようにコードの前後に空白を入れる必要があります．

コード `print();` の前後に空白を入れる

ただしバージョン1.5.6.1現在，句読点の直後には空白を入れなくてもコードとして認識されます．

このように，`print();` 後ろだけ空白を入れれば良い．`print()` ここも大丈夫．

これを変換すると以下のようになります．
“このように，print(); 後ろだけ空白を入れれば良い．print() ここも大丈夫．”

URLのケース

URLの場合は，句読点の後ろに半角スペースを入れなければURLとして認識されません．URL以外のコマンドも同じで，半角スペースが必要です．

こんな時， http://gohugo.io[Hugo] は前後に空白を入れる

Prism.js を使ったコードハイライト

PrismJS は，<pre><code class="language-lisp"> で始まるコードブロックをハイライト処理します． AsciiDoc の記法でコードを書くと，この形式に変換されます．

行番号のつけ方

PrismJS で行番号をつけるには，code 要素に line-numbers クラスを追加する必要があります． AsciiDoc では，言語指定の後ろに半角スペースを入れて line-numbers を追加すると，<code class="language-c line-numbers"> というマークアップが生成されます．

```lisp line-numbers
(cffi:define-foreign-library libuv
  (:darwin  (:or "libuv.1.dylib" "libuv.dylib"))
  (:unix    (:or "libuv.so.1" "libuv.so"))
  (:windows (:or "libuv.dll" "libuv-1.dll"))
  (t        (:default "libuv")))

(unless (cffi:foreign-library-loaded-p 'libuv)
  (cffi:use-foreign-library libuv))
```

上のコードは以下のように変換されます．

(cffi:define-foreign-library libuv
  (:darwin  (:or "libuv.1.dylib" "libuv.dylib"))
  (:unix    (:or "libuv.so.1" "libuv.so"))
  (:windows (:or "libuv.dll" "libuv-1.dll"))
  (t        (:default "libuv")))

(unless (cffi:foreign-library-loaded-p 'libuv)
  (cffi:use-foreign-library libuv))

コード・ブロックにタイトルを付けたい場合は，次のように記述します．

[source, lisp line-numbers]
.libuvのロード
----
(cffi:define-foreign-library libuv
  (:darwin  (:or "libuv.1.dylib" "libuv.dylib"))
  (:unix    (:or "libuv.so.1" "libuv.so"))
  (:windows (:or "libuv.dll" "libuv-1.dll"))
  (t        (:default "libuv")))

(unless (cffi:foreign-library-loaded-p 'libuv)
  (cffi:use-foreign-library libuv))
----

変換結果は次の通りです．

コード 1. libuvのロード

(cffi:define-foreign-library libuv
  (:darwin  (:or "libuv.1.dylib" "libuv.dylib"))
  (:unix    (:or "libuv.so.1" "libuv.so"))
  (:windows (:or "libuv.dll" "libuv-1.dll"))
  (t        (:default "libuv")))

(unless (cffi:foreign-library-loaded-p 'libuv)
  (cffi:use-foreign-library libuv))

コールアウトを実現するには

Asciidoctor はコールアウトを <b class="conum">(1)</b> というマークアップに変換します． PrismJS は，ソースコード中のマークアップをプログラミング言語の一部とみなして別の形式に変換してしまいます．ソースコード中のマークアップをそのまま残すには，“Keep Markup” プラグインを一緒にインストールします．あとは，スタイルシートでコールアウトの見栄えを設定します．

下のコードを変換してみます．

[source, c line-numbers]
.Idle basic
----
#include 
int main() {
    printf("Hello World\n");    // <1>
    return 0;
}
----
<1> コールアウト

コード 2. Idle basic

#include <stdio.h>
int main() {
    printf("Hello World\n");   (1)
    return 0;
}

コールアウト

数式の挿入

数式は MathJaxの設定をしていれば， Asciidoctorのstem に従って記述するだけで大丈夫です．まず文書の冒頭で，latexインタプリタを使う設定をします．

:stem: latexmath

あとはインライン数式の場合，stem:[\int_0^\infty f(x) dx] と書くと \(\int_0^\infty f(x) dx\) に変換され，MathJaxによって \(\int_0^\infty f(x) dx\) と表示されます．

ディスプレイ数式の場合は，

[stem]
++++
\int_0^\infty f(x) dx
++++

と書くと，

<div class="stemblock">
<div class="content">
\[\int_0^\infty f(x) dx\]
</div>
</div>

に変換され，

\[\int_0^\infty f(x) dx\]

と表示されます．