かんがるーさんの日記

最近自分が興味をもったものを調べた時の手順等を書いています。今は Spring Boot をいじっています。

Antora で生成するドキュメントサイトに antora-lunr で検索機能を追加する

概要

記事一覧はこちらです。

antora-lunr を使うと antora で生成するドキュメントサイトに検索機能を追加できると聞いたので、試してみます。

参照したサイト・書籍

  1. Mogztter / antora-lunr
    https://github.com/Mogztter/antora-lunr

  2. Mogztter / antora-site-generator-lunr
    https://github.com/Mogztter/antora-site-generator-lunr

  3. lunr-languages
    https://www.npmjs.com/package/lunr-languages

  4. MihaiValentin / lunr-languages
    https://github.com/MihaiValentin/lunr-languages

  5. LANGUAGE SUPPORT
    https://lunrjs.com/guides/language_support.html

目次

  1. npm install --save-dev antora-site-generator-lunr を実行する
  2. ドキュメントサイトを生成して検索機能を試してみる
  3. DOCSEARCH_LANGS=en,jaDOCSEARCH_LANGS=ja を指定してもダメでした。。。
  4. lunr-languages をインストールして日本語で検索できるようにする
  5. DOCSEARCH_INDEX_VERSION=latest を指定して最新バージョンのドキュメントだけ index が生成されるようにする

手順

npm install --save-dev antora-site-generator-lunr を実行する

antora-lunr のドキュメントを読むと、簡単に導入するのであれば antora-site-generator-lunr をインストールすればよいとのこと。

ksbysample-antora-playbook プロジェクトで npm install --save-dev antora-site-generator-lunr を実行して antora-site-generator-lunr をインストールします。

f:id:ksby:20210328233907p:plain

ドキュメントサイトに search component を表示するために antora-playbook.yml を以下のように変更します。

..........
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  supplemental_files: ./node_modules/antora-lunr/supplemental_ui

..........
  • supplemental_files: ./node_modules/antora-lunr/supplemental_ui を追加します。

ドキュメントサイトを生成して検索機能を試してみる

build ディレクトリを削除してから DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr npx antora --generator antora-site-generator-lunr antora-playbook.yml を実行します。

f:id:ksby:20210328235249p:plain

生成された build ディレクトリを見ると build/site/search-index.js が生成されています。

f:id:ksby:20210328235414p:plain

build/site/index.html をブラウザで開くと search component が画面上部に表示されて、asciidoctor と入力すると検索結果が表示されました! ただし結果が2重に表示されています。

f:id:ksby:20210328235722p:plain

また日本語で ツール と入力すると何もヒットしませんでした。

f:id:ksby:20210329000008p:plain

DOCSEARCH_LANGS=en,jaDOCSEARCH_LANGS=ja を指定してもダメでした。。。

Support for other languages の記述があったので、DOCSEARCH_LANGS=en,ja を追加して DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr DOCSEARCH_LANGS=en,ja npx antora --generator antora-site-generator-lunr antora-playbook.yml でドキュメントサイトを生成し直してみましたが、

f:id:ksby:20210329001053p:plain

結果は変わりませんでした。

f:id:ksby:20210329001213p:plain

DOCSEARCH_LANGS=ja に変更しても結果は変わらず。

lunr-languages をインストールして日本語で検索できるようにする

lunr を日本語で検索できるようにするには lunr-languages をインストールすればよいとの記事を見かけたので、インストールして日本語が検索できるようにしてみます。

まずは npm install --save-dev lunr-languages を実行して lunr-languages をインストールします。

f:id:ksby:20210329002025p:plain

In a web browser に従い、node_modules/antora-lunr/lib/generate-index.js を以下のように変更します。

'use strict'

const lunr = require('lunr')
require("lunr-languages/lunr.stemmer.support")(lunr)
require('lunr-languages/tinyseg')(lunr)
require("lunr-languages/lunr.ja")(lunr)
const cheerio = require('cheerio')
const Entities = require('html-entities').AllHtmlEntities
const entities = new Entities()

..........

  const lunrIndex = lunr(function () {
    const self = this
    self.use(lunr.ja)
    self.ref('url')
    ..........
  • 以下の3行を追加します。
    • require("lunr-languages/lunr.stemmer.support")(lunr)
    • require('lunr-languages/tinyseg')(lunr)
    • require("lunr-languages/lunr.ja")(lunr)
  • lunr(function () { ... } の中に以下の1行を追加します。
    • self.use(lunr.ja)

DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr npx antora --generator antora-site-generator-lunr antora-playbook.yml を実行します。

f:id:ksby:20210329002616p:plain

日本語で ツール と入力すると今度は検索結果が表示されました!

f:id:ksby:20210329002728p:plain

asciidoctor と入力しても検索結果が表示されます。日本語以外を入力しても問題ないようです。

f:id:ksby:20210329002845p:plain

DOCSEARCH_INDEX_VERSION=latest を指定して最新バージョンのドキュメントだけ index が生成されるようにする

検索結果が2重に表示されたのは v3.0 と v2.0 の2つのバージョンのドキュメントで index が生成されているためでした。Index only the latest version の記述がありましたので、DOCSEARCH_INDEX_VERSION=latest を追加して最新バージョンのドキュメントのみ index が生成されるようにします。

最初は DOCSEARCH_INDEX_VERSION=v3.0 と index を生成したい tag を指定するのかと思ったのですが、この設定では結果は何も変わらず、DOCSEARCH_INDEX_VERSION=latest と指定する必要がありました。

DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr DOCSEARCH_INDEX_VERSION=latest npx antora --generator antora-site-generator-lunr antora-playbook.yml を実行します。

f:id:ksby:20210329004140p:plain

日本語で ツール と入力すると今度は検索結果が1件だけ表示されました。

f:id:ksby:20210329004241p:plain

履歴

2021/03/29
初版発行。