🦕

Docusaurusでドキュメント管理の仕組みを構築してみた

2022/06/22に公開

3行まとめ

  • 非エンジニアの筆者が、Docusaurus(ドキュメント管理ツール)を試してみた記事です
  • 開発チームにおいては、NotionやConfluenceなどの定番ツールより使いやすい(かも?)
  • 無料で使えるのがありがてぇ。。

はじめに

ドキュメント管理って難しいですよね。
運用ももちろんですが、まずツール選びが大変、NotionやGoogle Docsなどなどたくさんありますが、どれが良いのか判断しづらいですよね。
現在所属しているチームでDocusaurusを利用することになり「オォォ、これはスゴイ!」ってなったので、紹介してみたいと思います。

Docusaurusとは?

Meta(Facebook)によって公開されているオープンソースのサイト構築ツールです。サイト構築ツールの中でも、特にドキュメントの管理やブログの作成などの静的サイト構築に強みがあります。
Build optimized websites quickly, focus on your content(ええ感じになっとるウェブサイトをサクッと作って、コンテンツに集中しようぜ! Translated by: 筆者) というキャッチコピーを掲げており、実際に利用してみたところかなり簡単にドキュメント管理の仕組みが構築できたため、こちらで紹介します。

公式ページはコチラから

Docusaurusの特徴

Docusaurusの特徴としては、

  • オープンソースのため無料で利用できる
  • Reactベースで書かれている、とてもシンプル
  • 一度作ってしまえば、あとはマークダウンの記述のみでコンテンツを追加できる
  • 非エンジニアの筆者でも構築ができた
  • 速い、すごく速い
  • 検索機能も簡単に追加可能
  • Gitで管理ができるため、差分比較が行える
  • 目に優しいナイトモードもデフォルトである

上記のような特徴があります。「 Docusaurusの3つの特徴 」などでまとめたいところでしたが、良い機能が多くまとまりがつきませんでした。

では、早速試してみたいと思います。

完成イメージ

https://iridescent-tarsier-893c49.netlify.app/

やってみよう

Docusaurusの公式サイトには、導入手順のチュートリアルが存在しています。

非常に分かりやすいシンプルな内容になっていますが、この公式チュートリアルでは ドキュメント管理機能に追加してブログ機能 も含まれています。

今回、私がやりたかったことはシンプルなドキュメント管理であったため、ドキュメント管理に特化したGitHubのリポジトリを作成しました。
今回の記事では、完成イメージのようなドキュメント管理に特化したサイトを作成したいという前提でサイトの構築を実施したいと思います。

1. GithubのリポジトリをCloneする

任意のフォルダで、以下のコマンドを実行してローカルにcloneを行ってください。

git clone https://github.com/tannerjohn65/docusaurus_template

or

gh repo clone tannerjohn65/docusaurus_template

2. 関連するパッケージをインストールして、立ち上げる

私の環境では、npmで管理を行っているため、パッケージをインストールするために以下のコマンドを実行します。

npm install

続いて、localhostを立ち上げます

npm start

完成イメージのURLと同様の画面が表示されていれば完了です。

2.記事を追加する

今回はテストとして、新たな記事を追加してみましょう。

今のdocs以下の構成は上記のようになっていると思います。

サイト上のサイドバー表示は以下です。

今回は、芥川龍之介に記事を追加するとして、akutagawa以下に、momotaro.mdというファイルを作成してみましょう。

任意の内容を記載します。今回の内容は青空文庫の内容を記載しました。

記載例:

# momotaro.md

好きな内容を記載する

保存すると。。。

上記のようにページが追加されていますね!

あとは、フォルダやファイルの名前を変更して好きな構成にしていただければ、オリジナルのドキュメント管理サイトが簡単に作成できると思います。

カテゴリー名やページ順の設定は、category.jsonの設定を変更することで設定が可能です。

画像の変更やヘッダーの追加、サイト名の変更などは、docusaurus.config.jsにて設定を行います。

このあたりの仕様については、公式ドキュメントに詳細が記載されているため、そちらに任せたいと思います。

3. サイトを公開する

今回利用したデモサイトは、Netlify(リンク)でホスティングを行いました。GitHubとWebhookで連携させることで簡単に公開ができます。
社内のみに共有したいドキュメントを管理したい場合はユーザー認証の仕組みを導入する必要がありますが、公開して問題のない場合はこれで完了です。

このあたりの仕組みについては、AWSやGCPのサービスを利用すれば導入は可能ですが、今回はデモのため対象外としたいと思います。

まとめ

無料で簡単に使える良いツールなので、是非試してみてください~~!

Discussion