AsciiDocでは、ソースハイライト (シンタックスハイライト) を有効化することで、ドキュメント内のソースコードを見やすくすることができます。

Source Highlighting

AsciiDocがビルトインでサポートしているシンタックスハイライターは以下の通りです。

タイプ ライブラリ HTML PDF EPUB3 Reveal.js

クライアントサイド

Highlight.js

✅

✅

ビルド時

CodeRay

✅

✅

✅

✅

Pygments

✅

✅

✅

✅

Rouge

✅

✅

✅

✅
参考リンク

上表の通り、Highlight.jsはクライアントサイドで動作するシンタックスハイライターです。JavaScriptで書かれており、ユーザのブラウザ上で実行されます。また、CDNから読み込めるため、ライブラリをインストールせずに利用可能です。

Highlight.jsを有効化する

環境

  • Asciidoctor 2.0.12

Important
 以降の説明は、スタンドアロンのHTMLファイルを出力する場合のみ有効です。つまり、JekyllやEleventyなどのサイトジェネレータを利用した際の埋め込み用HTMLコード出力では機能しません。この場合は、公式ドキュメントの手順に従って実装してください。

AsciiDocでHighlight.jsを有効化するには、source-highlighter 属性をドキュメントヘッダーで設定する必要があります。

:source-highlighter: highlight.js

これにより、変換後のHTMLには、スタイルシートへのリンクとHighlight.jsを実行するコードが自動的に挿入されます。 また、出力されるソースブロックは、シンタックスハイライトが適用されるように、変換されます。

テーマを変更する

デフォルトのGitHubテーマから変更するには、highlightjs-theme 属性を設定します。

Highlight.js のテーマ一覧は、デモページで確認可能です。 Demo - highlight.js

:highlightjs-theme: vs2015
:highlightjsdir: https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0

また、highlightjsdir 属性では、ライブラリやスタイルシートを読み込むベースのURLを変更することが可能です。 デフォルトでリンクされているライブラリは、若干バージョンが古いことがあるため、明示的に設定する必要があるかもしれません。

LjHtpvm
Figure 1. GitHubテーマ
dPckX2F
Figure 2. Visual Studio 2015テーマ
vCU7kbS
Figure 3. Dockerfile (Monokaiテーマ)

対応言語を追加する

Highlight.jsのデフォルトでサポートされていない言語を追加するには、highlightjs-languages 属性を設定します。 複数ある場合は、, で区切ります。

:highlightjs-languages: dockerfile, powershell

まとめ

  • AsciiDocでは、クライアントサイドで動作するHighlight.jsを利用できます。

  • Highlight.jsのテーマは変更可能です。

  • ライブラリを読み込む場所を変更可能です。

  • 対応言語を追加可能です。

コード例
:source-highlighter: highlight.js
:highlightjs-theme: vs2015
:highlightjsdir: https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0
:highlightjs-languages: dockerfile, powershell
属性名 説明

source-highlighter

利用するシンタックスハイライター

highlightjs-theme

Highlight.jsテーマ

highlightjsdir

Highlight.jsライブラリのパス

highlightjs-languages

対応言語の追加