Docusaurus の始め方
はじめに
このサイトはDocusaurusで作られています。
公式サイトに日本語の情報がないので、この記事でDocusaurusの始め方を紹介します。
Docusaurusとは？
Docusaurusは、開発者向けに静的なドキュメントサイトを手軽に構築するためのオープンソースのプロジェクトです。
Reactベースで動作し、Markdownでのコンテンツ作成が可能なため、初心者から上級者まで幅広く使われています。
どういった人々に適しているか
社内SEの勉強中の方にも、Docusaurusは非常に親しみやすいツールです。
プロジェクトのドキュメントを整理したり、ポートフォリオサイトを作成したりと、学習の成果を形にする絶好のチャンスです。
記事の目的説明
この記事では、Docusaurusの基本的なインストールから設定、ページの作成方法などを一歩一歩説明します。最終的には、自分だけのドキュメントサイトを公開できるようになることが目的です。
まだDocusaurusを使ったことがない方、または基本的な使い方に不安がある方も、この記事を読めば自信を持って始めることができるでしょう。次のセクションからは具体的なステップを見ていきましょう！
Docusaurusのインストールとセットアップ
Docusaurusを始めるためには、いくつかの前提条件と具体的なインストール手順が必要です。以下のガイドを参照してください。
必要な前提条件
Node.js: DocusaurusはNode.js上で動作するため、最新の安定版をインストールしてください。
npm: Node.jsのパッケージマネージャであるnpmも必要になります。Node.jsをインストールすると一緒にインストールされます。
インストール方法
プロジェクトフォルダの作成: 始めに、プロジェクト用の新しいディレクトリを作成します。
mkdir my-docusaurus-site
Docusaurusの初期化: 次に、以下のコマンドを実行してDocusaurusプロジェクトを初期化します。
npx create-docusaurus@latest my-docusaurus-site classic
ローカルサーバーの起動: 初期化が完了したら、以下のコマンドでローカルサーバーを起動し、ブラウザでプレビューできます。
cd my-docusaurus-site
npm run start
上記の手順でプロジェクトが作成されると、基本的なファイル構造とサンプルページが生成されます。
これを基に、自分だけのドキュメントサイトをカスタマイズしていきましょう。
基本的な構造とコンポーネント
Docusaurusプロジェクトの理解とカスタマイズを助けるため、プロジェクトの基本的なディレクトリ構造と主要なコンポーネントを解説します。
ディレクトリ構造の説明
- /docs: Markdown形式で書かれたドキュメントファイルが格納される場所です。
- /src: カスタムページやコンポーネントが格納されるディレクトリです。
- /static: 静的ファイル（画像やCSSなど）が置かれる場所です。
- docusaurus.config.js: サイトの設定やテーマ、プラグインの設定が行えるファイルです。
主要なコンポーネントとその使い方
- ドキュメントページ: /docsディレクトリ内でMarkdownを使用して作成します。見出しやリンクなどの基本的な書き方を学ぶと、効果的なドキュメントが作れます。
- カスタムページ: /src/pages内にReactコンポーネントとして作成します。HTMLとJavaScriptの知識で、自由にデザインできます。
- ナビゲーションバー: docusaurus.config.jsで設定し、サイト全体のナビゲーションを管理します。
Docusaurusプロジェクトの基本的な構造とコンポーネントを理解することで、自分のニーズに合わせてサイトをカスタマイズしやすくなります。これからのセクションで、具体的なページの作成やテーマのカスタマイズ方法について詳しく見ていきましょう。
ページの作成と編集
Docusaurusでのページ作成と編集は非常に直感的で、MarkdownやReactの基本的な知識だけで取り組めます。
以下のガイドでは、ドキュメントページとカスタムページの作成と編集方法を説明します。
ドキュメントページの作成と編集
新しいページの作成: /docsディレクトリに新しいMarkdownファイル（例：my-page.md）を作成します。
メタデータの追加: ページの先頭に以下のようなYAML形式のメタデータを追加します。
---
title: このページのタイトル
description: このページの説明
---
内容の追加: メタデータの下にMarkdownでページの内容を記述します。
サイドバーの設定: サイドバーに表示させる場合、sidebars.jsファイルで設定します。
カスタムページの作成と編集
新しいページの作成: /src/pagesディレクトリに新しいReactコンポーネント（例：MyPage.js）を作成します。
コンポーネントの定義: ページの内容とレイアウトをReactコンポーネントとして定義します。
ルーティングの設定: ファイル名と同じURLパスで自動的にルーティングされます。
Markdownでの文章作成
Docusaurusでドキュメントを作成する際、Markdownという軽量マークアップ言語が主に使用されます。Markdownの基本的な書き方を理解すると、手軽に整った文章を作成することができます。
見出しの作成
Markdownでは、ハッシュ記号 (#) を使って見出しを作成します。レベルに応じてハッシュ記号を増やします。
# 見出し1
## 見出し2
### 見出し3
テキストの装飾
太字: **太字** で太字にします。
斜体: *斜体* で斜体にします。
取り消し線: ~~取り消し線~~ で取り消し線を引きます。
リストの作成
番号なしリスト: ハイフン (-) で作成します。
番号付きリスト: 数字とピリオド (1.) で作成します。
- 番号なしリストA
- 番号なしリストB
1. 番号付きリスト1
2. 番号付きリスト2
- 番号なしリストA
- 番号なしリストB
- 番号付きリスト1
- 番号付きリスト2
リンクと画像
リンク: [テキスト](URL) で作成します。
画像:  で挿入します。
コードブロック
3つのバッククォート（```）でコードブロックを作成します。言語の指定も可能です。
console.log('Hello, World!');
表の作成
パイプ (|) とハイフン (-) を使用して表を作成します。
| Header 1 | Header 2 |
|----------|----------|
| Cell 1 | Cell 2 |
| Header 1 | Header 2 |
|---|---|
| Cell 1 | Cell 2 |
Markdownの基本的な書き方を習得すると、Docusaurusを使用して見栄えの良いドキュメントページを迅速に作成できます。一般的なエディターにはMarkdownのプレビュー機能も多く備わっているため、編集しながら確認することも可能です。
ビルドと公開
Docusaurusプロジェクトを完成させた後の最終ステップは、サイトを公開することです。このセクションでは、ビルドとサイトの公開について紹介します。
ビルド
Docusaurusプロジェクトを公開する前に、ビルドプロセスを実行する必要があります。ビルドプロセスは以下のコマンドで実行できます。
npm run build
このコマンドは、buildフォルダに静的ファイルを生成します。
公開
ビルドした静的ファイルは、単なるHTMLファイルなので、そのまま多くのホスティングサービスで公開できます。
build フォルダの中身をそのままホスティングサービスにコピーするだけで、公開完了です。
まとめ
この記事ではDocusaurusの始め方を紹介しました。
ドキュメンテーションの作成は、プロジェクトの成功にとって不可欠な部分であり、Docusaurusはそのプロセスをよりシンプルで楽しいものにするツールです。このガイドが、あなたのプロジェクトにDocusaurusを導入する第一歩となることを願っています。