Firefox 104

Firefox 104 が 8月23日にリリースされました。

Firefox 103 release note

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

Pickup for WebClass

WebClass に関係する変更はありませんでした。

今後の Firefox リリースについて

次回のリリースは 9月 20 日に予定されています。

Firefox Release Calendar

その他ブラウザのリリースはこちらにまとめています。

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

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 の不具合が発生する可能性は低いと思われます。

今後の Firefox リリースについて

次回のリリースは 8月 23 日に予定されています。

Firefox Release Calendar

その他ブラウザのリリースはこちらにまとめています。

Chrome 104

Google Chrome 104 が 8 月 2 日にリリースされました。

Chrome 104 release note

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

https://chromestatus.com/roadmap

https://developer.chrome.com/blog/new-in-chrome-104/

Pickup for WebClass

Cookie の Expires/Max-Age に設定できる値が最大 400 日になった

WebClass の動作には影響ないことを確認しました。

今後の Chrome リリースについて

次回のリリースは 2022 年 8 月 30 日に予定されています。

その他ブラウザのリリースはこちらにまとめています。

Google Chrome 100

Chrome 100 が 3 月 29 日にリリースされました。

Chrome 100 release note

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

https://chromestatus.com/roadmap

Pickup for WebClass

WebClass に影響ある変更はありませんでした。

今後の Chrome リリースについて

次回のリリースは 2022 年 4 月 26 日に予定されています。

その他ブラウザのリリースはこちらにまとめています。

こうして変更を追っていると、先進的で実験的な機能をどんどん追加する Chrome、全体を見据えたバランスを取ろうとする Firefox という印象を持ちます。Firefox ユーザーが減っているという話がありますが、寡占的な状況に陥らないよう応援したいところです。