Docusaurusドキュメント生成ツール

kc@example.com (kc kim) — Mon, 11 Mar 2024 01:03:00 +0900

Docusaurusとは

DocusaurusはFacebookが作成したオープンソースプロジェクトで、静的Webサイトを作るためのツールである。特に開発者が技術文書を書き、ホスティングする用途で使われる。Reactを基盤とした使いやすいドキュメントツールであり、Markdownで簡単に文書を書ける。

主な特徴には、MarkdownとMDXのサポート、カスタマイズ可能なレイアウトとテーマ、Algoliaによる検索機能、レスポンシブデザイン、多言語対応、プラグインシステム、ドキュメントのバージョン管理がある。

この記事ではmacOS環境でNode.jsとnpxを使って検証している。

% node -v
v21.6.2
% npx -v
10.2.4

Docusaurusにはプロジェクト作成用のScaffoldコマンドが用意されている。

$ npx @docusaurus/init@latest init [siteName] [template] [rootDir]
$ npx @docusaurus/init@latest init devkuma-mysite classic

作成後、ディレクトリへ移動してサイトを起動する。

$ cd devkuma-mysite
$ npm start

生成されるプロジェクトにはblog/、docs/、src/、static/などのディレクトリと、docusaurus.config.js、sidebars.jsなどの設定ファイルが含まれる。

最初のページはsrc/pages/index.jsを編集して変更できる。サイトヘッダーやナビゲーションは個別ページではなくdocusaurus.config.jsで設定する。開発中はファイルを修正するとブラウザが自動的に再読み込みされるため、変更箇所を確認しやすい。

DocusaurusはMarkdown、React、構造化されたサイドバーを使ってドキュメントサイトを作成・管理するための便利なツールである。文書用途であれば、主にdocs/、docusaurus.config.js、sidebars.jsを編集することになる。