Docusaurus v2のページにAlgolia DocSearchを導入する

サマリ

Docusaurus v2で、OSSのAPI Referenceサイトを作っていますが、公開しているAPIの数が多くて見ている方もしんどいので、検索できるようにしたい。
DocusaurusにはAlgoliaが提供しているDocSearchを使用できる機能が備わっているので、そちらを活用してみました。
結論から言って、非常に良いですよ。こんな感じ↓

#Docsaurus v2でこしらえた #p5toio のAPI Referenceサイトに検索サービスの #Algolia #DocSearch を導入してみた。簡単にできてよい。https://t.co/isBjF2feJ8 pic.twitter.com/zXolXE0GiD

— Tetsunori NAKAYAMA | 中山 哲法 (@tetunori_lego) May 26, 2020

なお、p5.toio: API Reference Siteで体験できます～。

前提

Docusaurus v2は既に導入済みとします。
/website 以下にDocusaurusが存在すると仮定し、公開対象のサイトURLは'https://tetunori.github.io/p5.toio/' であるとして話を進めます。

Algolia DocSearchへの申請

Algolia DocSearchにアクセスして、解析してもらうサイトのURLと自分のメールアドレスを入力します。で、JOIN THE PROGRAMのボタンを押すだけです。簡単。

ひたすら待つ

どうやら、DocSearchでは24時間毎にクロールしてくれるらしいく、その解析が終わったらメールアドレスへjsのsnippet送るからね、とダイアログが出てきます。

来たメールに返答する

私の場合は、30時間後くらいに、DocSearch Supportさんから第一報のメールがとどきました。ただ、snippetは書いてなくて、下記の様な文面で質問が書かれていました。

Hi there,

This is great news to know that you want to integrate DocSearch in your website. A good search experience is key to help your users discover your content.

We would love to help your project but we'll need to inject a small JavaScript snippet in the page: are you able to do that? Are you a maintainer of the website?

Let us know!

え、botじゃないの？人力なの？と感じながらも、恐る恐る、下記の様にメールで返答してみます。

Yes I'm able to do that because I'm a maintainer of the website.

すると、5時間後くらいに、下記の返答が来て、めでたくsnippetを手に入れました。

apiKey: '40d278d81283********a0c4e788be6d',
indexName: 'p5_toio',

Docusaurus上でsnippetを登録する

website/docusaurus.config.jsのthemeConfigに、下記の様にalgoliaプロパティを追加します。これだけです。

module.exports = {
  // ...
  themeConfig: {
    // ...
    algolia: {
      apiKey: '40d278d81283********a0c4e788be6d',
      indexName: 'p5_toio',
    },
  },
};

では、取り込まれているか、確認しましょう。

yarn run start

めちゃ簡単で、最高。

不具合

このサーチバー上で、適当な文字でEnterすると、クエリが発行されるのですが、そのページがもれなくPage Not Foundになります。Docusaurus本家のページでは、うまい事そこもDocSearchの結果を出してくれるのですが、まだ一般向けには未対応なのかな？？？今後に期待。

20200528追記：どうやらバグっぽくて、手元では修正も出来たので、ひとまずIssueとして起票してみました → https://github.com/facebook/docusaurus/issues/2827

Docusaurus v2はまだまだAlpha版なので不具合は多いですが、かゆいところに手が届くフレームワークなので大変良いです。皆様もぜひ。