1. Asciidoctorのコードハイライト機能を理解してHUGO上の記事にも反映する方法

HUGO環境上でAsciidoctorで記事を書いています。

HUGO上のAsciidoctorはStyleを無効化しているため期待したスタイルで描画されません。 これはHUGOのドキュメントで説明されています。

Content Formats @ HUGO

Command Option
asciidoctor: --no-header-footer --safe --trace -

HUGOではAsciidoctorで使用する必要なStyleは自分自身で明示的な指示が必要です。

この記事ではAsciidoctorのコードハイライト機能を理解してHUGO上の記事にも反映する方法を説明します。

2. 対応方法まとめ

  1. ドキュメント属性に:source-highlighter: highlightjsを指定

  2. 3行のpartialテンプレートを作成 highlightjs.html

  3. single.htmlか上記partialテンプレートを参照

これだけでハイライトを実現できます。

3. Asciidoctorのコードハイライト機能の動作を確認する

まずはHUGOのことは忘れてAsciidocotorでコードハイライトを実現し動作を確認します。

3.1. シンタックスハイライトを有効にするには

source-highlighter属性をドキュメントヘッダーに付けます。

11.13. シンタックスハイライトを有効にするには @ Asciidoctor 文法クイックリファレンス(日本語訳)

ここではhighlightjsを使用します。なぜならJavaScriptなのでインストールなど面倒な設定が必要なさそうだからです。

余談ですがこの「属性」や「ドキュメントヘッダー」などという言葉が分からない初心者の段階では情報収集にも苦労します。情報を集めたいけどどのようなキーワードで調べればいいのか分からないというのはあるあるだと思います。

3.2. HTMLに変換してソースコードを確認する

簡単な.adocと変換後のhtmlを比較して動作を確認します。

sample.adoc
:source-highlighter: highlightjs


== コードハイライトテスト

[source,python]
.py
----
import pandas as pd


print("Hello asciidoctor highlight.")

def test:
  print("Hello test.")

----
sample.html
<body class="article">
<div id="header">
</div>
<div id="content">
<div class="sect1">
<h2 id="_コードハイライトテスト">コードハイライトテスト</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="title">py</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">import pandas as pd


print("Hello asciidoctor highlight.")

def test:
  print("Hello test.")</code></pre>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2020-xx-xx xx:xx:xx JST
</div>
</div>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>
</body>

ドキュメント属性に:source-highlighter: highlightjsを指定することでHTMLタグに必要なClassを付与してくれています。

そして下記の３行

sample.html 抜粋
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>

をHUGOのテンプレートに反映すればハイライトできるようになります。

4. HUGOテンプレートに反映する

３行のHTMLを反映すれば良いのでpartialテンプレートを作成します。

highlightjs.html
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>

そして上記をsingle.htmlから参照します。

single.html
      {{ .Content }}
      {{ partial "highlightjs.html" . }}

これでHUGO上でもハイライトができるようになりました。

今回は以上です。