社内の開発ガイドラインの共有のために Docusaurus を導入したのがいい感じ

突然ですが、

とか

って大体のエンジニアがなんとなく見たことあると思います。そう、OSS のドキュメントの UI ですね。
あのドキュメントツールが Docusaurus です。

https://docusaurus.io/

今回はバックテックの開発ガイドライン策定の動きに合わせてエンジニアフレンドリーなツールを導入したお話です。

Docusaurus とは

冒頭で紹介した通りドキュメント管理ツールです。

• 信頼と安心の Meta 製
• OSS 中心に採用実績は十分
• 初期設定が簡単で、コンテンツを書くことに集中できる
• エンジニアフレンドリーな UI と機能
• SSG なので Hosting が簡単そう（後述）
• React Component を書くことも出来るので、好きなように遊ぶことも出来る

どんなサイトで使われているかは https://docusaurus.io/showcase?tags=favorite で見ることができます。

設定の流れ

1. Scaffold ファイルを作成
2. 自社に合わせて config ファイルを調整
3. sidebars.ts の調整

Scaffold ファイルを作成

$ npx create-docusaurus@latest documents classic --typescript を実行するだけ。
この時点で $ npm run start したらある程度のテンプレコンテンツで動きます。この Zero Config な設計はとてもありがたいです。

加えて以下の対応を行いました。

• 不要な Blog 機能のファイルを削除
• src/css/custom.css を弄って自社のテーマカラーに
• トップページも自社仕様に

config ファイルを調整

Docusaurus の機能は多岐にわたります。それらを管理しているのが、 docusaurus.config.ts です。

以下を調整しました。

• ナビゲーションバーの要素
• テーマやサイドバー
• i18nを ja 設定に
• HTML と title や favicon、ロゴの指定
• フッターの要素

ただのドキュメントツールとは言え、愛着は大事。バックテックではプロダクト内に登場する愛称「ポケセラさん」をロゴに設定したりしました。

sidebars.ts の調整

Docusaurus のサイドバーは2つの設定方法があります。

1. 自動設定

ディレクトリを指定するだけでサイドバーが表示されます。

export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};

ドキュメントの実体である Markdown ファイルでは以下のようにサイドバー内での順番を書くことで順番を指定できます。

---
sidebar_position: 2
---

# Title

2. 愚直に指定

愚直に配列で指定することも出来ます。バックテックではこちらを採用。
まだサイドバーの構造も大きく変わることもあるかと思い、一箇所で指定できたほうが並び替えが容易だろうと考えました。

import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  sidebar: [
    {
      type: "category",
      label: "Backend",
      items: [
        "backend/Introduction",
        "backend/Database",
        "backend/Route",
        "backend/Request Validation",
        "backend/UseCase",
        "backend/Entity",
        "backend/Repository",
        "backend/Autogenerates",
      ],
    },
    {
      type: "category",
      label: "Frontend",
      items: [
        "frontend/Introduction",
        "frontend/translate-your-site",
        "frontend/URLになる",
      ],
    },
  ],
};

export default sidebars;

以上の作業である程度自分好みの Docusaurus が出来ていると思います。

Hosting

SSG なのでビルドさえできればどこでも良いので、とりあえず GitHub Pages とかで良いだろうと考えていました。

問題発生

GitHub Pages に自社メンバーだけ表示できるように認証認可を入れるには Enterprise プランじゃないと駄目であることが発覚。
ドキュメントのためだけにプランアップグレードはしたくないと思ったので他のツールを探しました。

• 無料である
• 認証認可できる

この条件で探すと偶然にも今バックテックがメインで利用している Azure の Static Web App が当てはまりました。

Azure Static Web App

構築は Azure の Static Web App のガイドに従って進めると一瞬でした。
なんと自動的に GitHub Repository から Build & Deploy するための GitHub Actions の workflow YAML まで作成してくれます。ここも Zero Config。

認証認可

Azure Static Web App で認証認可をさせるには以下内容で staticwebapp.config.json をプロジェクトルートに置いてデプロイするだけ。

// 全体
{
  "routes": [
    {
      "route": "/login",
      "redirect": "/.auth/login/github"
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/*",
      "allowedRoles": ["superRoleName"]
    }
  ],
  "responseOverrides": {
    "401": {
      "redirect": "/login",
      "statusCode": 302
    }
  }
}

以下の記述だけで、GitHub を認証プロバイダーとして指定できます。ただこのままだと GitHub で認証できるだけで、実質的に GitHub のすべてのユーザーがドキュメントを閲覧出来てしまいます。

    {
      "route": "/login",
      "redirect": "/.auth/login/github"
    },

認可

ポイントは "allowedRoles": ["superRoleName"] です。
Azure Static Web App > ロール管理 にて、このロールを与えてユーザー招待することでホワイトリスト形式での認可が可能になります。

この方法で招待できる最大人数が25人というネットの情報も見つけたのですが、一次ソースではどこにも書かれておらず若干困惑しています。

Docusaurus 導入してみてどうだったか

• Meta によってメンテされていく安心感
• 設定が手軽で Deploy までが速い
• 目次や適切な文字の大きさなどのお陰で見やすい（Notion との違いは一体なんだろう🤔）
• ドキュメントの Git 管理ができる
• 内容について GitHub で議論・レビューが出来る
• まだ使っていない機能も使ってみたい

今のところメンバーからも好評です！ツールがイケてるとモチベも上がると思うので頑張ってガイドライン策定していきます！