Caution
 この記事では、 Asciidoctor および html5 バックエンドを選択して出力されるドキュメントについて説明しています。

Docinfoは、AsciiDocの機能の1つで、HTMLの head 部や記事のヘッダー、フッターにコンテンツを挿入できる機能です。 すべてのページで同じヘッダー、フッターを挿入したり、特定のページのみ異なるスクリプトブロックを挿入するような使い方ができます。

Important
 Docinfoは、すべてのバックエンドで機能しません。 HTMLやDocBookなどに変換できる一部のバックエンドでのみ機能します。

Docinfoを有効にするには、docinfo 属性を設定し、対応するDocinfoファイルを作成します。 Docinfoファイルは、適用したいドキュメントと同じ階層に置くか、docinfodir 属性でディレクトリを指定できます。

Docinfo属性値

docinfo 属性値は、ドキュメントにどのDocinfoファイルを適用するか制御します。

属性値には、private、shared、またはそれぞれのプレフィックスにコンテンツの挿入先(head, header, footer)を連結した値から選択できます。

Table 1. docinfo 属性値と対応するファイル名
docinfo属性値 ファイル名

private

private-head

<docname>-docinfo.html

private-header

<docname>-docinfo-header.html

private-footer

<docname>-docinfo-footer.html

shared

shared-head

docinfo.html

shared-header

docinfo-header.html

shared-footer

docinfo-footer.html
Warning
 ファイル拡張子はバックエンドによって異なります。上表は html5 の場合を示しています。
また正確には、outfilesuffix 属性値に合わせる必要があります。

private、shared プレフィックスに続く head、header、footer はそれぞれのコンテンツの挿入先を表しています。

head(ヘッド部)

コンテンツは、HTMLの <head> 要素内の最後に挿入されます。

header(ヘッダー)

コンテンツは、記事ヘッダー(#header)の上部に挿入されます。

footer(フッター)

コンテンツは、記事フッター(#footer)の下部に挿入されます。

Example 1. 複数の属性値

docinfo には、複数の属性値を設定できます。

ファイル名 foo.adoc
:docinfo: shared,private-footer

上の例では、共有のDocinfoファイル(ヘッド部、ヘッダー、フッター)を適用し、プライベートのフッターファイルが存在する場合は、さらにそれを適用します。プライベートのフッターファイル名は、foo-docinfo-footer.html になります。

Docinfoファイルを検索するディレクトリを変更する

Docinfoはデフォルトで、ドキュメントファイルと同じ階層にあるDocinfoファイルを検索します。 Docinfoファイルが別の場所にある場合、docinfodir 属性を設定して、この動作を変更できます。

docinfodir の属性値には、Docinfoファイルが保存されているディレクトリのパスを指定します。 属性値に絶対パスを使用した場合はそのまま使用され、相対パスを指定した場合は、ドキュメントファイルからの相対パスを検索します。

Example 2. docinfodir に相対パスを設定する

ドキュメントに以下のような属性値が設定されると、出力されるHTMLのhead部に、 common/meta/docinfo.html の内容が挿入されます。 このパスは、ドキュメントファイルからみたときの相対パスです。

:docinfodir: common/meta
:docinfo: shared-head

まとめ

  • head 要素、記事ヘッダー上部、記事フッター下部にコンテンツを挿入できる。

  • docinfo 属性値を設定し、対応するDocinfoファイルを作成する。

  • Docinfoは、デフォルトで、ドキュメントファイルと同じ階層にあるDocinfoファイルを検索する。

  • docinfodir 属性値でDocinfoファイルの保存場所を変更できる。

また、Docinfoファイル内で属性値を参照することも可能です。
Attribute substitution in docinfo files

使う機会があれば追記予定です。