Antora で生成するドキュメントサイトに antora-lunr で検索機能を追加する
概要
記事一覧はこちらです。
antora-lunr を使うと antora で生成するドキュメントサイトに検索機能を追加できると聞いたので、試してみます。
参照したサイト・書籍
Mogztter / antora-lunr
https://github.com/Mogztter/antora-lunrMogztter / antora-site-generator-lunr
https://github.com/Mogztter/antora-site-generator-lunrlunr-languages
https://www.npmjs.com/package/lunr-languagesMihaiValentin / lunr-languages
https://github.com/MihaiValentin/lunr-languagesLANGUAGE SUPPORT
https://lunrjs.com/guides/language_support.html
目次
npm install --save-dev antora-site-generator-lunr
を実行する- ドキュメントサイトを生成して検索機能を試してみる
DOCSEARCH_LANGS=en,ja
やDOCSEARCH_LANGS=ja
を指定してもダメでした。。。- lunr-languages をインストールして日本語で検索できるようにする
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 をインストールします。
ドキュメントサイトに 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
を実行します。
生成された build ディレクトリを見ると build/site/search-index.js が生成されています。
build/site/index.html をブラウザで開くと search component が画面上部に表示されて、asciidoctor
と入力すると検索結果が表示されました! ただし結果が2重に表示されています。
また日本語で ツール
と入力すると何もヒットしませんでした。
DOCSEARCH_LANGS=en,ja
や DOCSEARCH_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
でドキュメントサイトを生成し直してみましたが、
結果は変わりませんでした。
DOCSEARCH_LANGS=ja
に変更しても結果は変わらず。
lunr-languages をインストールして日本語で検索できるようにする
lunr を日本語で検索できるようにするには lunr-languages をインストールすればよいとの記事を見かけたので、インストールして日本語が検索できるようにしてみます。
まずは npm install --save-dev lunr-languages
を実行して lunr-languages をインストールします。
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
を実行します。
日本語で ツール
と入力すると今度は検索結果が表示されました!
asciidoctor
と入力しても検索結果が表示されます。日本語以外を入力しても問題ないようです。
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
を実行します。
日本語で ツール
と入力すると今度は検索結果が1件だけ表示されました。
履歴
2021/03/29
初版発行。