Docusaurusでマニュアルを作る #1 インストールから最初のドキュメントまで

ドキュメントを本格的に作り始めると、ほぼ例外なく同じ問題に出会います。README一枚では手に負えないドキュメントをどこに積み上げるか、という問題です。Notionは外部公開とバージョン管理が面倒で、ブログツールで作ると記事が時系列に並ぶだけでリファレンスとして使いづらいです。そのため多くのチームは、ドキュメントをコードのように扱う方式、つまりDocs as Codeへ移っていきます。マークダウンで書き、Gitで管理し、静的サイトとしてデプロイする方式です。

このシリーズは、その最初の一歩である静的サイトジェネレーターでドキュメントサイトを建てる方法を扱います。ツールはDocusaurusです。Reactで作られており、マークダウンの中でReactコンポーネントを使えるMDXと、多言語・バージョン管理を一級機能として内蔵している点が強みです。インストールはHugoやMkDocsより重いですが、その分だけ天井が高いです。

今回のシリーズはDocusaurusでマニュアルを作る全6回です。

• #1 インストールから最初のドキュメントまで ← 今回の記事
• #2 サイドバーと検索 — ドキュメントの情報構造を組む
• #3 コンテンツ作成 — コードブロック、Mermaid、admonition
• #4 Cloudflare Pagesでデプロイしてドメインを接続する
• #5 多言語とバージョン管理
• #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

今回の記事はDocusaurusが何を準備物として要求するのか、そして新しいサイトを作って開発サーバーで最初のドキュメントを表示するところまでを実際に動かしながら締めくくります。

準備物 — Node.js #

DocusaurusはNode.jsの上で動くツールです。そのため準備物はNode.js 18バージョン以上です。インストール後にバージョンを確認します。

node --version

Nodeをインストールすると、パッケージマネージャーのnpmも一緒に入ります。Hugoが単一バイナリで、MkDocsがPythonパッケージだったのとは違い、DocusaurusはJavaScriptのエコシステムの上で動きます。

新しいサイトを作る #

ジェネレーターがサイトの骨組みを一度に作ってくれます。classicテンプレートを使うと、ドキュメント・ブログ・基本テーマがすべて含まれた形で始められます。

npx create-docusaurus@latest my-docs classic

コマンドが終わると、my-docsフォルダの中に必要なファイルがすべて入り、依存関係までインストールされた状態になります。

最初のドキュメントを表示する #

作られたフォルダに入り、開発サーバーを立ち上げます。

cd my-docs
npm start

ブラウザでhttp://localhost:3000が自動的に開き、基本のドキュメントが現れます。ファイルを直すと画面がすぐに更新されます。ドキュメント本文はdocsフォルダに入っており、最初の画面はdocs/intro.mdです。このファイルを開いて内容を変えてみます。

---
sidebar_position: 1
---

# はじめに

私たちのチームの公式ドキュメントです。左のサイドバーから項目を選んでご覧ください。

sidebar_positionはサイドバーでの順序です。数字が小さいほど上に来ます。

フォルダ構造を理解する #

生成された構造の中で、すぐに知っておくべき場所はいくつかあります。

my-docs/
├─ docusaurus.config.js   # サイト設定
├─ sidebars.js            # サイドバー定義
├─ docs/                  # ドキュメント本文 (ここを埋めます)
│  └─ intro.md
├─ src/                   # カスタムページ・Reactコンポーネント
├─ static/                # 画像などの静的ファイル
└─ build/                 # npm run build の成果物 (デプロイ用)

ドキュメントを増やす作業は、docsの下にマークダウンファイルを足す作業です。ただしHugoがフォルダ構造をそのままサイドバーにしていたのとは違い、Docusaurusはsidebars.jsでサイドバーを定義します。その方法は次回で本格的に扱います。

まとめ #

今回の記事では、Node.jsを準備し、create-docusaurusでサイトを生成して開発サーバーで最初のドキュメントを表示するところまで終えました。インストールが重い代わりに、すでにReactやJavaScriptに慣れているチームであれば、最も自然に手になじむツールです。

次回はサイドバーと検索を扱います。ドキュメントが数十編に増えても読者が道に迷わないよう、sidebars.jsで情報構造を設計する段階です。