Docusaurusで静的サイトを構築する - セットアップからコンテンツ作成まで
どうも、Shinyaです。この記事では、Docusaurusを使用して静的サイトを構築する手順について解説します。プロジェクトの作成から開発サーバーの起動、ドキュメントの追加までを扱います。
- Docusaurusで静的サイトを構築したい人
- ドキュメントサイトやブログを作成したい人
- React/TypeScriptベースの静的サイトジェネレーターを探している人
- Markdownでコンテンツを管理したい人
Docusaurusとは
Docusaurusは、Metaが開発・メンテナンスしているオープンソースの静的サイトジェネレーターです。Markdown/MDXでコンテンツを記述でき、Reactベースのカスタマイズが可能です。ドキュメントサイトやブログの構築に適しています。
ソースコードはGitHubで公開されています。
Docusaurusの主な特徴
| 特徴 | 説明 |
|---|---|
| Markdown/MDX対応 | コンテンツをMarkdownおよびMDXで記述可能。Reactコンポーネントの埋め込みにも対応 |
| React/TypeScriptベース | UIのカスタマイズやプラグイン開発をReact/TypeScriptで行える |
| ドキュメント機能 | バージョニング、サイドバー、検索などドキュメントサイトに必要な機能が標準搭載 |
| ブログ機能 | タグ、フィード、ページネーションなどのブログ機能を標準で提供 |
| ホットリロード | ファイルを保存すると変更が即座にブラウザに反映される |
Docusaurusは多くのオープンソースプロジェクトで使用されています。一例として、atprotodart.comのドキュメントサイトがDocusaurusで構築されています。
事前準備
Docusaurusの実行にはNode.jsが必要です。Node.jsの導入がまだの場合は、nvmでNode.jsのバージョン管理を行うの記事を参考にインストールできます。
Docusaurusプロジェクトの作成
npm init docusaurus@latestの実行
以下のコマンドを実行して、Docusaurusプロジェクトを作成します。
npm init docusaurus@latest
コマンドを実行すると、対話形式でプロジェクトの設定が求められます。
プロジェクト名の入力
最初にプロジェクト名（ディレクトリ名）の入力が求められます。任意の名前を入力します。
? What should we name this site? › website
テンプレートの選択
使用するテンプレートの選択が求められます。標準的なサイト構成で始める場合はclassicを選択します。
? Select a template:
❯ classic (recommended)
Git Repository
Local template
classicテンプレートには、ドキュメント、ブログ、カスタムページの3つのコンテンツタイプが含まれています。
開発言語の選択
TypeScriptを使用するかどうかの選択が求められます。TypeScriptの型チェックを活用する場合はTypeScriptを選択します。
? Which language do you want to use?
JavaScript
❯ TypeScript
選択が完了すると、プロジェクトの作成と依存パッケージのインストールが自動的に実行されます。
開発サーバーの起動
npm startの実行
プロジェクトの作成が完了したら、プロジェクトディレクトリに移動して開発サーバーを起動します。
cd website && npm start
開発サーバーが起動すると、ブラウザが自動的に開き、Docusaurusの初期ページが表示されます。デフォルトではhttp://localhost:3000でアクセスできます。
ホットリロード
開発サーバーの起動中は、ファイルを編集して保存すると変更がブラウザに即座に反映されます。この機能はホットリロードと呼ばれ、コンテンツの編集結果をリアルタイムで確認できます。
ドキュメントの作成
docsフォルダの構成
Docusaurusのドキュメントコンテンツは、プロジェクトルートのdocsフォルダに配置します。docsフォルダ内のMarkdownファイルが、サイトのドキュメントページとして自動的に認識されます。
ドキュメントファイルの作成例
docsフォルダにMarkdownファイルを作成すると、ドキュメントページとして表示されます。以下はdocs/hello.mdの例です。
---
sidebar_position: 1
---
# Hello
This is my first document.
フロントマター（ファイル先頭の---で囲まれた部分）でsidebar_positionを指定すると、サイドバーでの表示順序を制御できます。数値が小さいほど上に表示されます。
ファイルを保存すると、ホットリロードにより変更がブラウザに反映され、サイドバーに新しいドキュメントが追加されたことを確認できます。
主要なフロントマターオプション
| オプション | 説明 |
|---|---|
sidebar_position | サイドバーでの表示順序を指定 |
sidebar_label | サイドバーに表示されるラベルを指定（省略時はタイトルが使用される） |
title | ドキュメントのタイトルを指定 |
description | ドキュメントのメタディスクリプションを指定 |
slug | カスタムURLパスを指定 |
まとめ
この記事では、Docusaurusを使用して静的サイトを構築する手順について解説しました。
Docusaurusは、Metaが開発しているオープンソースの静的サイトジェネレーターで、npm init docusaurus@latestコマンドで対話形式のプロジェクト作成が可能です。docsフォルダにMarkdownファイルを配置することでドキュメントページを追加でき、ホットリロードにより編集結果をリアルタイムで確認できます。
参考リンク: