VuePressでAlgolia DocSearchを有効化する（申請パターン）

概要

VuePressでAlgolia DocSearchでの検索を有効にします。

VuePressの標準機能でAlgoliaの検索機能は組み込まれているので有効化すること自体は簡単です。
しかし、AlgoliaとDocSearchが何者なのかを理解していなかったために時間がかかったので備忘録として残します。

AlgoliaのINDEXを作成するには下記の2パターンがありますがこの記事では申請してクロールをお願いするパターンを紹介します。

• Algolia DocSearchにクロールの申請をしてINDEX作成をお任せする。
• Algolia DocSearch-Scraperを使用してクロール（INDEX作成）を自前で行う。

※VuePress 0.X系を使用しておりますが1.X系もほぼ変わりません。

実際にAlgolia検索を有効にしたサイトが下記です。

• 稼働サイト
  • チラ裏のメモ帳 | チラ裏のメモ帳
• GitHub
  • Lycheejam/my-cheatsheet

Algolia有効化前（標準の検索機能）	Algolia有効化後

目次

参考サイト様

• AlminのサイトをOSSドキュメントツールのdocusaurusで作り直した | Web Scratch

環境

環境はあまり関係ありませんが一応記載しておきます。

• Mac OS X Mojave 10.14.3
• VisualStudio Code 1.32.2

$ node -v
v11.12.0
$ npm -v
6.7.0
$ vuepress -V
0.14.10

VuePress標準検索機能とAlgolia検索の違い

2行でまとめると以下の様になります。

• VuePress標準はタイトルとh1・h2タグのみを検索
• Algoliaを使用すると全文検索

VuePressでは標準機能としてドキュメントの検索機能が実装されています。
元々ドキュメント管理用の静的サイトジェネレータなので当然といえば当然ですね。

下記の公式ドキュメントにあるようにVuePress標準の検索機能ではタイトルとh2（##）・h3（###）タグのみ検索対象となっています。

Built-in Search only builds index from the title, h2 and h3 headers, if you need full text search, you can use Algolia Search.
Default Theme Config #Search Box | VuePress

ガバ翻訳するとこんな感じ。

標準で組み込まれてる検索機能はタイトルとh2・h3タグしかインデックスしないから
もし、全文検索が必要だったらAlgoliaを使ってね

全文検索を使う場合にはAlgoliaを使用するように公式ドキュメントで案内されています。

Algoliaとは

VuePressでAlgolia検索を有効化するお話の前にAlgoliaが何者なのかを理解する必要があります。
とは言ってもGoogle翻訳に頼るしかないのでざっくりとしたイメージしかお話できませんが...

ものすごくざっくり言うとSaaSで提供されてるすごい検索エンジン。
サイトのインデックスをAlgolia側に提供することで高度な検索機能が使えるようになります。
しかもCDN（エッジサーバいっぱいあるから）でレスポンスがすっごい早い（ミリ秒単位）と言う代物です。

もっと詳しくはここらへんを読んでください。

• How Algolia Works | Getting started | Guide | Algolia Documentation

AlgoliaのIndexってなに

Algoliaで全文検索を有効化するためにはAlgoliaに「ここを検索してね！」と指示してあげる必要があります。
また、検索結果に重み付け（ランキング化）することも必要です。
そこで使用されるのがインデックスです。

Algolia DocSearchとは

技術文書のINDEX作成に特化したAlgoliaのクローラです。

• クロール（クローリング）とは - IT用語辞典 e-Words

VuePressに組み込まれているAlgolia検索機能はこのDocSearchが使われています。（？）
Algoliaコミュニティによって運営されており条件を満たせば無料で24時間毎にクロールしインデックスを作成してくれるすごいやつです。

また、自動クロールを申請するには一定の条件があるため条件に該当しない場合は自身でDocSearchを使用してインデックスを作成できます。

詳細はここらへんをどうぞ。

• Algolia's Ecosystem | In depth | Getting started | Guide | Algolia Documentation
• What is DocSearch?

Algolia 検索を有効化する方法

Algoliaについての情報を整理したところで（全然整理できてない）
Algolia DocSearchのINDEXを作成（Algoliaに提供）する方法は2つあります。
本記事では1つ目の方法を紹介します。

1. DocSearchへ申請し24時間毎に自動でクロールしてもらう方法
2. DocSearch-Scraperを使って自前でIndexを作成しAlgoliaへアップロードする方法

1つ目はDocSearchを使用して自動クロールしてもらう方法。
この方法が一番簡単で楽ですが使用するにあたりいくつか条件があるため条件を満たせない方は強制的に2を選択する必要があります。

2つ目が自前でIndexを作成して適宜Algoliaへアップロードする方法。
DocSearchのクローラであるDocSearch-ScraperはGitHub上にOSSとして公開されているので自身でクロールを実行可能です。
これを実践した記事が下記です。

• Algolia DocSearch-Scraperでクロールを実行する（INDEXを作成する） - あとらすの備忘録

Algolia DocSearchのクロールを利用可能な条件

自動クロールの利用条件についてはこちらにチェックリストがあります。

• WHO CAN APPLY?

条件は下記の4つです。

・You must be the owner of the website, or at least have the power to update its content.
You'll have to include a JavaScript snippet to enable DocSearch.

・Your website must be publicly available.
We do not host index for websites that are available behind an authentication or a private network.

・Your website must be a documentation website.
We do not index blogs or commercial content.

・Your website must have some final content.
We won't index empty websites nor those filled with lorem ipsum placeholder content.
Please, wait until you have written some documentation before applying.
We would be happy to help you as soon as you have a steady design.
WHO CAN APPLY?

ガバ翻訳するとこんな感じ。

• 申請者が申請されたWebサイトの所有者であること
• インターネットからアクセス可能なWebサイトであること（認証付きとかもダメ。クロールできないよ）
• ドキュメントサイトであること。ブログとか商用サイトはダメよ。
• ページ（ドキュメント）がいくつか用意されていること。クロール対象がないとクロールできないよ。

あとは申請を手動で処理しているので申請から承認までうまく行けば2,3日で承認がおります。
OSSの場合は優先的に申請を処理するとも記載されています。

DocSearchの自動クロールを申請してAlgolia検索を有効化する

前段で述べたAlgolia検索を有効化する方法の2つの内、1つ目の方法を紹介します。
大体の方はこの方法で良いんじゃないでしょうか。

Algolia DocSearchに申請

下記のサイトからAlgolia DocSearchに申請します。
もちろん前述した利用条件を満たしていることが必要です。

• DocSearch: Search made for documentation

2、3日で承認可否のメールがきます。
すると再度、いくつかの質問があるので返信してあげます。

• あなたはWebサイトの所有者（メンテナ）？
• small JavaScript snippetが必要？

なんのこっちゃわからんので下記のブログ様を参考にさせていただきました。

• AlminのサイトをOSSドキュメントツールのdocusaurusで作り直した | Web Scratch

Hi algolia support team

I use Google Translate because I can not speak English.

This is using VuePress on my website.
You can check the repository on GitHub.
・ https://github.com/Lycheejam/my-cheatsheet

Thank you.

一応、GitHubのリポジトリとVuePressを使っていることを返信しました。
向こうが欲しがっている情報だったかはわかりませんが...

もうなんかこれでいろいろ察してくれたようで2日後くらいに返事が来ました。

• APIキー発行したからこれ使ってね！
• 作ったconfig（jsonファイル）はここに置いてあるよ。
  • docsearch-configs/cheatsheet_kitigai.json at master · algolia/docsearch-configs
  • 修正したかったらプルリクエスト送ってね！
• 君のメールアドレスは既にAlgoliaへ登録済みだったからユーザのダッシュボードに紐付けておいたよ！
  アクセス許可したら検索の利用状況（Analytics）が見れるよ！

こんな感じです。
INDEX作成用のconfigファイルが作成されたのでクローラはこれを見てINDEXを作成してくれます。
あとはVuePress側の設定をします。

VuePressでAlgolia検索を有効化

VuePressでAlgoliaを使用するのは簡単でconfig.jsにDocSearchから通知されたAPIキーとINDEX名を記載すれば完了です。

• Default Theme Config #Algolia Search | VuePress

公式ドキュメントに習い下記の様に記載すればOK

• config.js

module.exports = {
  themeConfig: {
    algolia: {
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>'
    }
  }
}

あとは検索にヒットしそうなワードを検索して有効化されてるかを確認してください。 公式ドキュメントには設定ファイルが作成された時点でクロールされる旨の記載があるのでINDEXは済んでいるはずです。

• FAQ #How often will you crawl my website?

雑感

INDEX作成（クロール）をCIに組み込んで自動ビルド・デプロイが完了するとクロールを開始するみたいなことを実現したかった。 現状できていないのでとりあえず申請部分だけ記事にしました。