DocusaurusはReact BootstrapやJest、Ionicなど多くの有名なアプリのドキュメントサイトで使われているドキュメント構築アプリです。
今回は、「Docsaurusを使ってサイトを作ってみたい！」という方に、Docusaurusのインストール方法を解説します。
Docusaurusのインストール方法
Node.jsのバージョンが18.0以上である必要があります。インストールしていない場合はインストールして下さい。
node -vでNode.jsのバージョンを確認できます。
Docusaurus をインストールする最も簡単な方法は、以下のコマンドを実行する方法です。このコマンドによりサンプルページを含むサイトが作成されます。
npx create-docusaurus@latest my-website classic
# typescript を使う場合
npx create-docusaurus@latest my-website classic --typescript
my-website は任意のサイトの名前を指定できます。classic はテンプレート名です。
クラシックテンプレートには、ドキュメント、ブログ、カスタム ページ、CSS フレームワーク（ダーク モードをサポート）が含まれる@docusaurus/preset-classic というプリセットが含まれています。
クラシックテンプレートを使用すると、非常に簡単に実行でき、後に慣れてきたときにカスタマイズもできます。
プロジェクトの構造の概要
クラシックテンプレートを指定し、サイト名を my-website とした場合、my-website/ ディレクトリが生成されます。
このディレクトリ内には以下のような役割のフォルダやファイルがあります。
/blog/ー ブログのマークダウンファイルが含まれています。ブログプラグインを無効にしている場合、ディレクトリを削除することができます。また、pathオプション変更して、blog 以外の名前に変更することもできます。/docs/– ドキュメントのマークダウンファイルが含まれています。
sidebars.jsでドキュメントのサイドバーの順序をカスタマイズします。/blog/と同様、ディレクトリを削除したり、名前を変更することもできます。/src/– ページやカスタマイズシタReactコンポーネントなどの非ドキュメントファイルがあります。
ドキュメント以外のファイルを厳密にsrcフォルダに置く必要はありませんが、srcフォルダに集約する事で何らかのリンティングや処理を行う時に便利です。/src/pages– このディレクトリ内の JSX/TSX/MDX ファイルは Web サイトページに変換されます。
/static/– 静的ディレクトリです。ここにあるコンテンツはすべて、ビルド時にbuildディレクトリのルートにコピーされます 。/docusaurus.config.js– サイト構成を含む構成ファイルです。/package.jsonー DocusaurusのウェブサイトはReactアプリです。npmパッケージは好きなものをインストールして使うことができます。/sidebars.js– サイドバーに表示する見出しの順序を指定するために使用されます。
開発サーバーの実行
サイトを起動します。
cd my-website
npx docusaurus start
http://localhost:3000 を開きます。
ダークモードでは上記のようなページが表示されました。画像には表示されていないですが、フッターもあります。
ヘッダーの「Tutorial」をクリックすると以下のページが表示されました。
TutorialやBlogの各ページはmdファイルを元に構築されています。
Docusaurusのビルド
Docusaurus は最新の静的Webサイトジェネレーターであるため、Web サイトを静的コンテンツのディレクトリに構築し、Web サーバーに配置して表示できるようにする必要があります。ウェブサイトを構築するには以下を実行します。
npm run build
ビルドファイルは/build に出力されます。
ビルドファイルは、GitHubやVercel、Netlifyのような静的ファイルのホスティングサービスに展開できます 。
Docusaurusのバージョンを更新する
Docusaurus バージョンを更新する方法はたくさんありますが、おすすめの方法は、package.json に記載されているバージョン番号を希望のバージョンに手動で変更することです 。
{
"dependencies": {
"@docusaurus/core": "3.8.1",
"@docusaurus/preset-classic": "3.8.1",
// ...
}
}
@docusaurus/ から始まるパッケージは同じバージョンを使用する必要があります。
次に、package.jsonを含むディレクトリで、installコマンドを実行します:
npm install
アップデートが正常に行われたことを確認するには、以下を実行します。
npx docusaurus --version
まとめ
今回はDocusaurusのインストール方法を解説しました。
1つのコマンドでドキュメントサイトやブログサイトの土台となるファイルを簡単に生成することができました。
wikiのようなシンプルなサイトを作りたい場合は、サンプルファイルを参考にすれば簡単に記事を書く事ができます。
