Zenn
🦖

VSCode + Docusaurus で最高のドキュメント作成環境を構築する

2022/12/04に公開
Docker
VS Code
npm
Markdown
Docusaurus
tech

TL;DR

  • VSCode で Docusaurus のローカル環境（Docker コンテナ）を構築する
  • 開発環境は、Dev Containers（VSCode の拡張機能）を使うと便利
  • Docusaurus は、Markdown(+MDX) ベースでドキュメントやブログの静的 Web サイトを作成できるツール

はじめに

みなさんは、ドキュメントを作成する時、何を使っていますか？
Microsoft Office や Google ドキュメントといったオフィススイートを使用していますか？
それとも、Confluence のような Web ベースの Wiki でしょうか。
GitHub リポジトリで Markdown を書いている方もいるかもしれませんね。

ドキュメントではないですが、弊社が提供しているクラウドネイティブ道場のチュートリアルでは、Material for MkDocs を使用していたりします。
MkDocs は Python ベースで開発されている人気のドキュメントサイトジェネレータです。

今回は、Mkdocs よりも好きになれそうな Docusaurus のローカル環境を構築してみます。
個人的にいいなと思う Docusaurus のポイントについては、別日のアドベントカレンダー内で投稿（勝手にシリーズ化）しようと思いますので、とりあえずは Docusaurus のデフォルトページの表示までを確認してみます。

Docusaurus って？

Meta（旧：Facebook）が開発している Markdown(+MDX) ベースでドキュメントやブログの静的 Web サイトを作成できるツールです。
ドキュサウルスかわいいですね💓

docusaurus-icon
キーボードで遊んでるドキュサウルス

VSCode + Docusaurus の構成内容

早くドキュサウルスに会いたいですが、その前に今回構築するローカル環境の構成内容について整理しておきます。

ローカル環境は、Dev Containers（VSCode の拡張機能）を使用して構築します。
大まかな流れは次の通りです。

  1. Dev Containers の設定ファイルを作成（プロンプトに従って作成）
  2. 作成した設定ファイルに基づいて Docker イメージをビルドしてコンテナに接続（Dev Containers が自動でやってくれます）
  3. Docusaurus のインストールと初期化

devcontainers
環境のイメージ

Dev Containers を使えば、Docker コマンドを自分で叩かなくてもイメージが作れて接続も簡単なので、初めて知ったときは感動しました。
設定ファイルを Git リポジトリ等で共有すれば誰でも同じ環境がつくれるので、今回に限らず非常に便利です。
また、ローカル環境は、Docker をインストールしておくだけでよいので、環境が汚れなくてとてもよいです。
コンテナ技術って本当に素晴らしいですね。

弊社に来る前はバックエンドの開発を数年やっていましたが、アサインされたプロジェクトでコンテナを使っているところは存在しませんでした。
もっと普及してもいいのになぁと思う今日この頃です。

前提条件

次の項目については実施済みであることを前提に構築します。

  • VSCode がインストール済みであること
  • Dev Containers（VSCode の拡張機能：ms-vscode-remote.remote-containers） がインストール済みであること
  • Docker が使えること（Docker デーモンが起動していること）
    • Docker Desktop をインストールするのが一番楽です

ドキュサウルスに会いに行こう！

それでは環境の構築をはじめましょう。

Dev Containers の設定ファイル作成

まずは、空のフォルダを VSCode で開きましょう。
フォルダ名は任意のもので OK です。今回は、hello-docusaurus にしました。

VSCode でフォルダを開いたら、左下の緑の >< マークをクリックしてパネルを開きます。

パネルを開く
パネルを開く

開いたパネルから、Add Dev Container Configuration Files を選択します。

Dev Containers の設定ファイルを追加
Dev Containers の設定ファイルを追加

以下をチェックして、OK を選択します。

  • image: Ubuntu(Jammy)
  • Features
    • Git（Git 管理したい場合は選択）
    • Node.js（Docusaurus で使用するので必須）
    • Docker in Docker（アドベントカレンダーの別記事にて、コンテナ化するときに必須）

イメージとインストールする機能を選択
イメージとインストールする機能を選択

すると、次のような JSON ファイルが生成されます。（コメント部分は省略）

.devcontainer/devcontainer.json
{
	"name": "Ubuntu",
	"image": "mcr.microsoft.com/devcontainers/base:jammy",
	"features": {
		"ghcr.io/devcontainers/features/docker-in-docker:2": {},
		"ghcr.io/devcontainers/features/git:1": {},
		"ghcr.io/devcontainers/features/node:1": {}
	}
}

コンテナに接続

左下の緑の >< マークをクリックしてパネルを開きます。
開いたパネルから、Reopen in Container を選択すると、イメージのビルドが行われ、起動したコンテナに接続します。

イメージのビルドとコンテナの起動
イメージのビルドとコンテナの起動

正常にコンテナが起動すると、自動でコンテナに接続されます。
ターミナルで各種インストールされたツール群が使用できることが確認できます。

コンテナへの接続
コンテナへの接続

Docusaurus をインストールしてデフォルトページを表示

Docusaurus 公式のインストールガイドに従ってインストールしてみます。
サイト名は my-website、テーマは classic になっています。

npx create-docusaurus@latest my-website classic

コマンドを実行すると、Ok to proceed? (y) という確認メッセージが出るので、y を入力して Enter キーで進みます。

それでは、ディレクトリを移動して、ドキュサウルスに会いに行きましょう！
次のコマンドを実行してしばらくすると、VSCode で勝手に Docusaurus のデフォルトポート（3000 番）にポートフォワードしてくれて、ローカルのブラウザが開きます。

cd my-website
npm start

Docusaurus デフォルトページ
Docusaurus デフォルトページ

やったね🙌

最後に

とってもかわいいドキュサウルスに会えましたね✨
今回構築した環境でドキュサウルスといっぱい遊びましょう🦖

脚注

  1. 企業の規模等、特定の条件下では Docker Desktop は有料なので、有償ライセンスを回避するために WSL 上に Docker をインストールしています。 ↩︎

Discussion