Antora でドキュメントをかけるように練習だ！

はじめに

普段、ブログとかで Markdown を利用することが多いですが、大きめのドキュメントを書くときなどは AsciiDoc でかけると良い感じにまとめられたりします。そのなかでも、Antora はファイルを構造化しながら良い感じに静的サイトを作成できるツールです。少し触ってみたので、そのとき学んだことをまとめていこうと思います。

https://github.com/Wataru-Toriumi/antora-sample

どんな感じで進めていくの？

ディレクトリ構造

まず全体像です。ディレクトリ構造としては下記の通りです。

$ tree .
.
├── README.md
├── antora-playbook.yml
├── antora.yml
├── modules
│   └── guides
│       ├── nav.adoc
│       └── pages
│           ├── index.adoc
│           └── new-page.adoc
├── package.json
└── pnpm-lock.yaml

各ファイルの説明

• antora-playbook.yml
  • ビルドの設定
• antora.yml
  • コンポーネントの設定
• modules 配下
  • 関連ドキュメントの格納場所

antora-playbook.yml

site:
  title: Antora Sample Site
  start_page: antora-sample-site:guides::index
content:
  sources:
    - url: .
      branches: HEAD
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
output:
  dir: ./public
  # ビルド前に出力ディレクトリをクリアする
  clean: true

antora.yml

name: antora-sample-site
version: "1.0"
title: Antora Sample Site
nav:
  - modules/guides/nav.adoc

modules

├── modules
│   └── guides
│       ├── nav.adoc
│       └── pages
│           ├── index.adoc
│           └── new-page.adoc

ビルド後

ビルドするとこんな感じに表示できるようになります！

まとめ

まだ触りしか触れていないので、もう少し触ってやっていきたいですね。