Vercelで組織内部向けブックスタイルのドキュメント

ドキュメント文化を組織にインストール

リーガルテック会社であるMNTSQさんでは 社内ドキュメントをGitHub管理でメンテナンスしながら作り上げていくようにしていたらしいです。そこではGitbookでブックスタイルのウェブサイト化し、検索性などの問題を解決してますっていうのを、みました。Gitbookを利用しており、検索機能や目次、SSO認証等が完備されていますが、こちらは有料なのです。GitbookがCLIアプリじゃなくなった時点でフォークし、最新のnode.js環境下でもつかえるようにしたのが、Honkitです。こちらはOSSです。

組織内部向けドキュメントと言えば・・

GitHubなら、無料でプライベートリポジトリ作れるので、内部向けドキュメントを保管するのに好適な場所なのですよね。

組織のルールとかそういうドキュメントが閲覧できるようにしたいです。

しかし、GitWikiって検索性がショボいです。ブラウザエクステンションを導入すれば
検索能が上がるらしいですが、組織構成員にはそれすらメンドウに思う人がいそう。GitDiscussionsも検索性がショボいです。このようにGitHub上のUIはお世辞にも閲覧に適していません。検索機能は貧弱です。組織の人の中には、Google検索のような能力をあらゆる局面で期待する人もいますので、これが課題でした。

おこないたいこと

組織内部のひとしか見られないウェブページをHonkitでつくりたいと思いました。Basic認証というのが簡単そうだとおもいました。たとえば、GitHub EnterpriseおよびGitBook契約すれば、解決すると思いますが、なるべく無料でおこないたいです。

そんなときにVercelを知ることに...

無料のホスティングサービスを検索していたら、まずNetlifyにぶちあたりました。このサービスは、Honkitのドキュメンテーションが保存されているので、少しだけなじみがありました。

Netlifyのばあい、Basic認証が有料枠だそうです。さらに検索をかけると、Cloudflare Workersとくみあわせて認証をやらせるというのも, しるにいたりました。それなら無料だとおもいます。さらに、Cloudflareにも無料ホスティングサービス枠があるようです。CloudflarePagesというそうです。これにより、Basic 認証も有効になります。これもおそらく無料です。

いろいろ検索していると、Vercelというホスティングサービスもやっているところが、Basic認証も無料でできるみたいな情報をえました。

たしかZenn.devのブログが認証のはりかたを教えてくれております。

手順

• Vercel にサインアップ
• GitHub リポジトリに接続
• Honkit SSG で html ファイル (docs directory under Git repo.)を作成
• zenn.dev サイトから middleware.js をコピー
• Vercel サイトで環境変数の設定 (BASIC_AUTH_USER and BASIC_AUTH_PASSWORD) を行いました
• middleware.js を GitHub リポジトリの docs ディレクトリにアップロードしました。
• deployしました！

Refs.

zenn.devサイトでBasic認証のしかたをおしえてくれた方に感謝します。ドキュメントライティングの本がさいきんに出て、未読なのですが、ぜひ読んでみたいです！

• https://zenn.dev/monicle/articles/vercel-plain-middleware-basic-auth
• https://zenn.dev/awtnb/articles/6e77a44c568cf7
• https://note.com/takahiroanno/n/ne7e510a06cb9
• https://www.amazon.co.jp/dp/B0BXSYF2N4/
• https://honkit.netlify.app/
• https://qiita.com/fehde/items/17a2bfff8f5a5767c600
• https://pages.github.com/
• https://dockteck.github.io/honkit/basis.html

おまけ1：GitHubPagesについて復習

GitHubPagesっていうウェブサイトをつくる機能がございます。これだと、リポはプライベートだけど、サイトはパブリックとなってしまいます。リポにmdファイルをならべたてたうえで、HonKitもしくはGitBookなどで, docsディレクトリのしたに、静的にサイト生成すれば、デプロイしてくれます。

たとえば、おかねをつめば、サイト側もプライベートにできます。GitHub Enterpriseをアレするおかねがありません。

おまけ2：ウェブサイト側でIPアドレス制限を加える?

それだと、出社しているあいだしかアクセスできません。もちろんプロキシもしくはVPNをさせば、できるようになりますが、それもひとによってはメンドウかんじるので、できれば、避けたいです。

おまけ3：mdソースだけ提供してそれ以降は各自のローカルでやってもらう？

HonKitのインストールや使い方をしらせることにより、各自のローカル環境で、honkit serveみたいにやってもらうってのが、手っ取り早いかな？GitHub Private repoのしたに、SUMMARY.mdなどをおいておいたうえで、honkit serveのやりかたをしるしておきます。そうすれば、ローカル環境でブックスタイルのUIが実現するからhttp://localhost:4000を参照するようにしてもらいます.