Caution
 2023-07-09 現在、11ty (Eleventy) を使ったWebサイト構築に移行しています。

AsciiDocで手軽にWebサイトをしたいが、AsciiDocをメインに完全サポートしているツールは Antora くらいしかない。

awesome-asciidoc.adoc · main · Eclipse Working Groups / AsciiDoc WG / asciidoc.org · GitLab

静的サイト生成ツールを自作するのも面倒なので、 Asciidoctor の出力するHTMLをそのまま公開することにする。
ナビゲーション機能はまだ作ってないので、とりあえずヘッダーにトップページへのリンクだけでも貼っておく。

ついでにGitLab PagesでWebサイトの構築を自動化する。

概要

GitLab PagesとAsciidoctorを利用して、Webサイトを作成する方法を紹介する。

仕様

  • GitLab Pagesの機能で public ディレクトリを公開する。

  • コンテンツは public ディレクトリ下で管理する。

  • 公開するHTMLファイルは、 CI実行時に asciidoctor コマンドで .adoc ファイルから変換する。

ディレクトリ構造例
📒 repository
  📂 public (1)
    📁 highlight (2)
    📂 modules (3)
      📂 asciidoc (4)
        📂 pages
          📄 example.adoc (5)
    📁 styles (6)
    📄 index.adoc (7)
  📄 .gitlab-ci.yml (8)

  1. 公開するWebコンテンツのルート。

  2. Highlight.js コンテンツ。

  3. モジュールディレクトリ。モジュール: 管理するコンテンツのグループの単位。
    modules 以下の構造はAntoraを参考にしている。
    https://docs.antora.org/antora/latest/standard-directories/

  4. モジュール名。何でも良い。

  5. 公開するページ。AsciidoctorでHTMLに変換し、.html ファイルとして公開する。

  6. CSSファイルを格納。

  7. トップページ。各ページへのリンクを集約。

  8. GitLab CI/CD設定ファイル。

Webサイト作成

GitLab CI/CD設定

  1. GitLab上で空のプロジェクトを作成します。

  2. ローカルで下図のように index.adoc と .gitlab-ci.yml を作成します。

    📒 repository
  📂 public
    📄 index.adoc
  📄 .gitlab-ci.yml
    ファイル名 index.adoc
    = AsciiDocでWebサイトを作成する

== AsciiDoc
以下、Wikipediaからの引用。
[quote,AsciiDoc - Wikipedia,https://ja.wikipedia.org/wiki/AsciiDoc]
____
link:https://ja.wikipedia.org/wiki/AsciiDoc[AsciiDoc]は軽量マークアップ言語のひとつである。
意味論的にはlink:https://ja.wikipedia.org/wiki/DocBook[DocBook] XMLと同一であるが、対人可読な文書記述形式であり、文書の(論理)構造を意味付ける規則が平文形式である。
ゆえに構文解析器を介することなく、テキストエディタなどを用いてAsciiDocで記述された文書を作成・閲読できる。
____
    ファイル名 .gitlab-ci.yml
    image: asciidoctor/docker-asciidoctor (1)

pages:
  stage: deploy
  script:
    - asciidoctor public/index.adoc (2)
  artifacts:
    paths:
      - public (3)
    exclude:
      - "**/*.adoc" (4)

    1. 公式から Dockerイメージ が提供されているので、それを利用します。

    2. index.adoc ファイルをHTMLに変換し、同じディレクトリに出力します。

    3. ジョブの成果物を指定します。GitLab Pagesでは、公開するディレクトリを public にする必要があります。

    4. 変換元の .adoc ファイルは不要なので、成果物から除外します。

  3. ファイルをコミットおよびプッシュします。

    作成したファイルをGitLab上にpushすると、自動的にパイプラインが実行されます。
    パイプラインの実行状況は、サイドバーの CI/CD > Pipelines から確認できます。

    eN99CP0

    正常に実行されると Settings > Pages からWebページを確認できます。

    ZTeXRDz
    eYKzZI3

追加のページを作成する

  1. public ディレクトリの下に modules/<module>/pages/ ディレクトリを作成し、 newpage.adoc ファイルを追加します。

    📒 repository
  📂 public
    📂 modules
      📂 asciidoc
        📂 pages
          📄 newpage.adoc (1)
    📄 index.adoc
  📄 .gitlab-ci.yml

  2. asciidoctor の変換対象ファイルに public/**/pages/*.adoc を追加します。

    ファイル名 .gitlab-ci.yml
    ...
  script:
    - asciidoctor public/index.adoc public/**/pages/*.adoc
...

    これにより、 コンテンツをモジュール単位で分割して管理し、公開できます。

カスタムスタイルシート適用

CSSの適用は、AsciiDocの stylesheet 属性で設定します。
属性はファイルに書かず、コマンド引数で全体に適用します。

Apply a Custom Stylesheet | Asciidoctor Docs

適用するCSSファイルは、 Asciidoctor stylesheet factory で作成するか、 asciidoctor-skins で公開されているものが利用できます。

  1. public/styles/ にCSSファイルをコピーします。

    📒 repository
  📂 public
    📁 modules
    📂 styles
      📄 site.css (1)
    📄 index.adoc
  📄 .gitlab-ci.yml

  2. 以下のように、 linkcss と stylesheet 属性をコマンド引数で設定します。

    ファイル名 .gitlab-ci.yml
    ...
  script:
    - asciidoctor public/index.adoc public/**/*.adoc
      -a linkcss (1)
      -a stylesheet="$CI_PAGES_URL/styles/site.css" (2)
...

    1. HTMLにCSSを埋め込む代わりにリンクさせます。

    2. HTTPでアクセスできるCSSファイルのパスを指定します。

    Note

    $CI_PAGES_URL は GitLab CI/CD変数 です。
    GitLab Pagesで公開するときのURLが設定されます。
    Tip
    正しく設定したのにスタイルシートが更新されない場合

    ブラウザやCDNのキャッシュが残っている可能性があります。

ソースハイライト設定

ソースブロックの構文ハイライトは、 source-highlighter 属性で設定します。
組み込みの構文ハイライターは以下の通りです。

Syntax Highlighting | Asciidoctor Docs

今回は、追加のライブラリをインストールする必要がない Highlight.js を使います。

Highlight.js設定

  1. 以下のページからハイライトする言語を選んでダウンロードします。
    https://highlightjs.org/download/

  2. zipファイルを展開したら、 highlight.min.js ファイルと適用したい .css ファイル選んでを public 下にコピーします。

    Warning
    		 .css ファイルは github.min.css に名前を変更する必要があります。
    追加ファイル

    • public/highlight/styles/github.min.css

    • public/highlight/highlight.min.js

      📒 repository
  📂 public
    📂 highlight
      📂 styles
        📄 github.min.css (1)
      📄 highlight.min.js (2)
    📁 modules
    📁 styles
    📄 index.adoc
  📄 .gitlab-ci.yml

  3. .gitlab-ci.yml で、 asciidoctor コマンド引数にて source-highlighter と highlightjsdir 属性を設定します。

    ファイル名 .gitlab-ci.yml
    ...
  script:
    - asciidoctor public/index.adoc public/**/*.adoc
      -a linkcss
      -a stylesheet="$CI_PAGES_URL/styles/site.css"
      -a source-highlighter="highlight.js" (1)
      -a highlightjsdir="$CI_PAGES_URL/highlight" (2)
...

フッター作成

AsciiDocの Docinfo 機能を使って、ヘッダーやフッターを作成できます。 こちらでもDocinfoについて説明しています。

今回は全ページに同じフッターを適用します。

  1. public と同じ階層に docinfo ディレクトリを作成します。

  2. docinfo-footer.html ファイルを作成します。フッターとして追加したい内容を書きます。

    📒 repository
  📂 docinfo
    📄 docinfo-footer.html (1)
  📁 public
  📄 .gitlab-ci.yml
    ファイル名 docinfo-footer.html
    <div id="footer">
    <div id="footer-text">
        <p class="tableblock text-center">
            Made with AsciiDoc.
        </p>
    </div>
</div>
    ファイル名 .gitlab-ci.yml
    ...
  script:
    - asciidoctor public/index.adoc public/**/*.adoc
      -a linkcss
      -a stylesheet="$CI_PAGES_URL/styles/site.css"
      -a source-highlighter="highlight.js"
      -a highlightjsdir="$CI_PAGES_URL/highlight"
      -a nofooter (1)
      -a docinfodir="$(pwd)/docinfo" (2)
      -a docinfo="shared" (3)
...

    1. 既存のフッターを完全に置き換える場合は nofooter 属性を設定します。

    2. Docinfoファイルが保存されているディレクトリを指定します。相対パスで指定した場合、.adoc ファイルからの相対パスになるため、絶対パスで指定しています。

    3. Docinfoを有効にする ための属性です。