Asciidoc on heppoko blog

asciidoctor-pdf で見出し前の改ページを無効にする

Mon, 30 Sep 2024 00:00:00 +0900

asciidoctor-pdf で PDF を作成したときに、見出しレベル２の前に改ページが自動挿入されて無駄に余白があるページがあったので、これを無効化する方法です。

PDF 作成時に指定するテーマファイルで設定します。

https://docs.asciidoctor.org/pdf-converter/latest/theme/heading/#chapter

これを踏まえ、heading-chapter で break-before を auto に指定すれば改ページが無効になりました。

heading:
 chapter:
 break-before: auto

ただ、auto なので、場合によっては改ページされる場合もあるかもしれません。

尚、上記の設定は doctype が book の場合のみ有効なようです。

参考 URL

https://docs.asciidoctor.org/pdf-converter/latest/theme/heading/#chapter

Asciidoc で include ディレクティブを使用している場合の画像へのパス

Thu, 26 Sep 2024 00:00:00 +0900

画像を読み込んでいるファイルを、別の階層にあるファイルから include ディレクティブで読み込むと、相対パスの位置が変わってしまいます。

画像を読み込んでいるファイルを単体で表示したときにはそのファイルからの相対パスになりますが、include しているファイルを表示したときには、include しているファイルからの相対パスになってしまいます。

同様のことで悩んでいる方はそれなりにいるようで、実際私もかなり困っています。

とりあえずの解決方法としては、私にとっては以下の方法が一番役に立ちました。

https://stackoverflow.com/questions/75919047/images-in-various-locations-in-included-asciidoc-files

ちょっと手間ですが、include 直前で imagedir を都度セットします。

:imagesdir: hoge
include::hoge/included_file.adoc

ただし、多重で include している場合は上記では上手くいきません。
この場合は、試行錯誤の結果、以下のようにすることで上手くいきました。

ifdef::imagesdir[:imagesdir: {imagesdir}/hoge]
ifndef::imagesdir[:imagesdir: hoge]

include::hoge/included_file.adoc

imagesdir が既に定義されている（＝別のファイルから include されている）場合は、現在の imagesdir に付加する形で imagesdir を再定義します。
imagesdir が定義されていない（＝別のファイルから include されていない）場合は、前述と同じように imagesdir を定義します。

参考 URL

https://stackoverflow.com/questions/75919047/images-in-various-locations-in-included-asciidoc-files

Jekyll で Asciidoc を使用する

Thu, 12 Sep 2024 00:00:00 +0900

markdown だけでなく asciidoc も使えたら便利なので。

以下の記事で作成した環境に対して asciidoc を使えるようにします。

https://kuttsun.blogspot.com/2024/09/jekyll-docker.html

調べたところ以下のプラグインを使えば出来そうだったので、これを使ってみます。

https://github.com/asciidoctor/jekyll-asciidoc

Gemfile の変更

ドキュメントの通りに、Gemfile に以下を追加します。

group :jekyll_plugins do
 gem 'jekyll-asciidoc'
end

_config.yml に以下を追加します。

plugins:
 - jekyll-asciidoc

尚、jekyll-asciidoc は他のプラグインより先に記述する必要があるそうです。
詳細は以下を参照してください。

https://github.com/asciidoctor/jekyll-asciidoc?tab=readme-ov-file#plugin-ordering

これで、_post フォルダ内に asciidoc で書いたドキュメントを追加すれば OK です。
ファイル名は Jekyll の決まりとして、YYYY-MM-DD-title.adoc のように日付が入っている必要があります。

https://jekyllrb-ja.github.io/docs/posts/

以下、サンプル通りに記事を作成してみました。

= Sample Page
:page-layout: post
:page-permalink: /sample/
:url-asciidoctor: https://asciidoctor.org

This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].

[source,ruby]
puts "Hello, World!"

ただし、layuout は post に変更しています。
レイアウトについては以下。

https://qiita.com/a999/items/6c29ce072c19448ea579

これできちんと表示されることを確認しました。

include ディレクティブを使用するときの相対パス

asciidoc では include ディレクティブを使用して他の asciidoc ファイルを読み込むことができますが、このままやっても上手く描画されませんでした。
同様の内容が issue に挙がっていました。

https://github.com/asciidoctor/jekyll-asciidoc/issues/182

ベースディレクトリの設定がデフォルトではプロジェクトルートになっているので、ソースディレクトリとなるように設定すれば良さそうです。

https://github.com/asciidoctor/jekyll-asciidoc?tab=readme-ov-file#specifying-the-base-directory

_config.yml に以下を追記すれば上手くいきました。

asciidoctor:
 base_dir: :docdir
 safe: unsafe