どうも、Shinyaです。
この記事では、静的ジェネレータのDocusaurusを使用して、マークダウンベースのWebサイトを構築する方法を紹介します。
Docusaurusは、ソーシャルメディアのFacebookで有名なMeta Platformsが開発を主導している、オープンソースの静的ジェネレータツールです。Docusaurusを使用すると、テンプレートに従うだけで簡単にマークダウンベースのWebサイトを構築することができます。
参考までに、私が開発しているOSSプロジェクトのatproto.dartのWebサイトでもDocusaurusを使用しています。
事前準備
Docusaurusをセットアップするためにはnpmコマンドを使用するため、事前にnpmコマンドを使用できるようにNode.jsをインストールしておく必要があります。
次の記事を参考にnvmを使用して最新のNode.jsをインストールしてください。
Docusaurusをセットアップする
Docusaurusをセットアップする方法はとても簡単です。
まず、Docusaurusで作成するWebサイトを保存したいディレクトリを用意し、コマンドプロンプトで次のnpmコマンドを実行してください。次のnpmコマンドを実行すると、公式から提供されているDocusaurusを初期化する際のCLIツールが起動します。
npm init docusaurus@latest上記のnpmコマンドを実行すると、Docusaurusのインストールとセットアップが始まるので、コマンドプロンプトに出力された質問に回答していきましょう。
Docusaurusのセットアップ
Need to install the following packages:
create-docusaurus@3.8.1
Ok to proceed? (y)→ Docusaurus v3.8.1をインストールするかどうかを聞いているので、「y」を入力してエンターキーを押下してください。「y」を入力してエンターキーを押下するとDocusaurusのインストールが始まるので、完了まで気長に待機してください。
What should we name this site?→ これからDocusaurusで作成するWebサイトのプロジェクト名を入力します。何も入力せずにエンターキーを押下するとデフォルトの「website」が使用されるので、特にこだわりがなければそのままエンターキーを押下して大丈夫です。
? Select a template below... › - Use arrow-keys. Return to submit.
❯ classic (recommended)
Git repository
Local template→ DocusaurusでWebサイトを作成する際のテンプレートを選択します。こちらも特にこだわりがなければ「classic (recommended)」で十分なので、そのままエンターキーを押下してください。
? Which language do you want to use? › - Use arrow-keys. Return to submit.
JavaScript
❯ TypeScript
→ Docusaurusで作成するWebサイトの開発言語を選択します。矢印キーを使用してTypeScriptを選択してからエンターキーを押下します。
セットアップの完了
ここまで入力が完了したらDocusaurusがWebサイトの初期化を開始するので、Webサイトの初期化が完了するまで気長に待ちましょう。
Webサイトの初期化が完了すると、コマンドプロンプトで次のような結果が出力されます。
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
[SUCCESS] Created website.
[INFO] Inside that directory, you can run several commands:
`npm start`
Starts the development server.
`npm run build`
Bundles your website into static files for production.
`npm run serve`
Serves the built website locally.
`npm run deploy`
Publishes the website to GitHub pages.
We recommend that you begin by typing:
`cd website`
`npm start`
Happy building awesome websites!Docusaurusで作成したWebサイトを起動する
さて、ここまでの作業でDocusaurusを使用してWebサイトを初期化できたので、早速このWebサイトを起動してみましょう。
まずは、次のコマンドで作成したWebサイトのルートディレクトリに移動します。
cd website次に、コマンドプロンプトで次のnpmコマンドを実行します。
npm start上記のnpmコマンドを実行すると、Webサイトのビルドが開始します。Webサイトのビルドが完了したら、次の画像のようにDocusaurusが作成したWebサイトを確認することができます。
Webサイトのドキュメントを更新する
Docusaurusでは、マークダウン形式のドキュメントを更新することで、Webサイトに表示するドキュメントを簡単に変更することができます。
マークダウン形式で更新可能なドキュメントは、Docusaurusで作成したWebサイトの開発ディレクトリのルートにある「docs」フォルダに格納されています。
また、docsフォルダにマークダウン形式の任意のドキュメントを追加することで、難しい追加の実装を一切行うことなく、Docusaurusで作成したWebサイトにコンテンツを反映することが可能です。
試しに、docsフォルダの直下に「hello.md」という名前のマークダウンファイルを作成し、次のように編集してみましょう。
---
sidebar_position: 3
---
# Hello
*Hello, World!*Docusaurusはホットリロードをサポートしているので、マークダウンやソースコードの修正を行った後でローカルサーバーの再起動は必要ありません。
ローカルサーバーを起動したままでも、修正したマークダウンやソースコードは自動で検出された上でビルドされ、ローカルで起動しているWebサイトに自動かつ瞬時に反映されます。
そうすると、上記で追加したマークダウンファイルの内容が、次の画像のようにWebサイトに反映されたことを確認できます。
