AsciiDoc と Antora でマニュアルサイトを構築しました

2022年8月23日

9:08 PM

AsciiDoc と Antora でマニュアルサイトを構築しましたはコメントを受け付けていません

弊社 LMS WebClass には、学生の学習履歴を可視化する「学習記録ビューア」という機能があります。学習記録ビューアを使い始めるために必要な権限設定、プラグインによる機能拡張もあり、ユーザーの方に使っていただくためにはドキュメントの充実が必須です。学習記録ビューア専用のマニュアルサイトを以前から公開していたのですが、先日プチリニューアル（内部的にはなかなか大きな更新）しました。その際、サイト構築にドキュメントサイトジェネレータ Antora を使用することになりました。Antora 使用事例として興味を持つ人もいるかなと思い、構築プロセスを公開します。

今回リニューアルしたマニュアルサイトはこちらです。

Antora とは

Antora は、AsciiDoc からドキュメントサイトを生成するツール
デモサイト
Antora のドキュメントサイト自体も Antora で生成されている
複数のリポジトリにコミットされている AsciiDoc から一つのサイトを生成できる
Git ブランチやタグからドキュメントの「バージョン」を規定できる
- 例えば “v1”, “v2” のようなタグまたはブランチを作り、バージョン毎にドキュメントを管理する
- サイトにアクセスした人は見たいバージョンを切り替えることができるようになる

リニューアル前の状況

マニュアル本文は全て AsciiDoc で書いている
- 1 ページ 1 adoc ファイル
サイトの外殻は Pug で書いていた。Pug を HTML に変換する際、AsciiDoc を Asciidoctor (Asciidoctor.js) で HTML に変換し埋め込んでいた
Asciidoctor PDF を使って、AsciiDoc を PDF に変換し、サイトからダウンロードできるようにしている
社内でセルフホストしている GitLab でバージョン管理

課題

マニュアル本文は AsciiDoc を編集するので楽だが、ナビゲーションメニューを更新するために Pug を編集する必要があり、面倒くささは拭いきれなかった
- ドキュメントの充実のためには更新のしやすさは必須
検索機能がなかった
目次がページのタイトル下に表示されるが、下にスクロールすると見えなくなるので、文の多いページだと全体が俯瞰しづらかった

リニューアル後

構成

マニュアルリポジトリには、複数ある製品のマニュアル AsciiDoc ファイルが全て登録されている
マニュアルサイトリポジトリには、antora-playbook.yml という設定ファイルが登録されている
- antora-playbook.yml に AsciiDoc が登録されているリポジトリやバージョン情報を記述することで、Antora のコマンド一発でサイトが生成できるようになる
CI/CD
1. マニュアルリポジトリで AsciiDoc ファイルを変更しコミットする
2. GitLab CI の Multi-project pipelines によりマニュアルサイトリポジトリのパイプラインが起動
3. マニュアルサイトリポジトリのパイプライン内でサイト生成ジョブ実行
4. サイト生成完了後、Manual Job でデプロイ可能となる

リニューアル前の課題は解決したか

ナビゲーションメニュー等の高頻度で更新される部分は全て、 Antora の設定ファイル及び AsciiDoc を編集することで変更できるため、マニュアル更新が楽になった
検索機能を簡単に付けることができた
- 実装の詳細は後述
ページをスクロールしても常に目次が表示されるようになった

多言語化

こちらを参考に、バージョン切り替えの仕組みを使って言語切り替えを実現しました。

antora-playbook.yml:

content:
  sources:
  - url: https://git.lan.datapacific.co.jp/webclass/manual-integrated-portfolio.git
    start_paths:
      - integrated-portfolio/admin/ja
      - integrated-portfolio/admin/en

この方法だと、逆に通常のバージョン切り替えができなくなります。言語毎に別サイトを生成してもよかったかもしれません。

検索機能

Antora Lunr Extension を使っている
Antora コマンドによるサイト生成時に検索用インデックスも生成される
- サイト表示後はオフライン検索できる

antora-playbook.yml:

antora:
  extensions:
    - require: '@antora/lunr-extension'
      languages: [ja]

まとめ

マニュアルサイトに必要な機能は全て揃い、マニュアル更新のハードルはかなり下がりました。これから一番大切なコンテンツ改善を進めていきます。

Firefox 103

by matsukawa

2022年8月12日

4:20 PM

Firefox 103 はコメントを受け付けていません

Firefox, ブラウザリリース

Firefox 103 が 7月26日にリリースされました。

Firefox 103 release note

以下のリンクに主な変更点の情報が記載されています。

Pickup for WebClass

Stream API によって生成されれたオブジェクトが Transferable オブジェクトになった

　Stream API によって生成された ReadableStream、WritableStream、TransformStream オブジェクトがTransferable オブジェクトになりました。これにより、マルチスレッド処理を行う環境において別のスレッドにこれらのオブジェクトを転送する際、元のスレッドでは利用できないように指定することが可能になりました。

　WebClass で利用している pdf.js において Stream API は利用されていますが、すでにこれらのオブジェクトを Transferable オブジェクトとして扱っている他のブラウザでは pdf.js による不具合は報告されていません。そのため、Firefox においてもこの変更によって WebClass の不具合が発生する可能性は低いと思われます。