アプリをリリースするとき、ドキュメントを置くサイトをどうしようかよく悩みます。今回、Docusaurusというドキュメントサイト構築ツールを利用しましたので紹介します。

Docusaurusとは？

ドキュメントやマニュアルをWebで公開するためのサイトを構築するツールです。最近、Projmoというメモアプリをリリースしましたが、このアプリのドキュメントサイトの構築に、Docusaurusというドキュメントサイト構築ツールを使いました。

docusaurus.io

Sphinxとかと似たようなものですね。昔はSphinxをよく使っていましたが、SphinxだとRead the docsテーマを使っても見た目が今どきにならないので、どうしようかといろいろ探していたところ、Docusaurusにたどり着きました。

Docusaurusのいいところ

見た目がいい

見た目がいいと気持ちが良いものです。 Docusaurusは今どきだけど、癖がないデザインで、とても使いやすく感じます。

構造がシンプル

とてもシンプルです。ドキュメントの管理もしやすいです。

Markdownベース

ドキュメントをMarkdownで書けます。今どきですね。

Reactベース

今どきのWebアプリはだいたいReactベースだと思います。 DocusaurusもReactベースなのでとっつくやすく、デプロイ方法も統一できてよい感じです。

ドキュメントサイトを作成する

それでは早速つくってみましょう。

以下のようなサイトがつくれます。

https://docs.projmo.com/

インストール

まずはdocusaurusをインストールします。私は宗教上の理由でyarn使いなので、yarnを使ってインストールします。

yarn create docusaurus my-website classic

最初の変更

インストールした直後のサイトは、サービスページが表示されるようになっています。つくりたいのはドキュメント用のサイトなので、サービスページは使わないようにします。以下の記事を参考にさせていただき、すぐできました。ありがとうございます。

griponminds.jp

変更するファイル

ソースコードはとてもシンプルで分かりやすいです。基本的な見た目は、docusaurus.config.jsファイルだけ修正すれば大丈夫です。アイコンなどもこのファイルで指定します。

記事は、docs/とblog/に置きます。サイト共通の画像ファイルはstatic/img/に置きます。

アプリバー

docusaurus.config.jsファイルのnavbarセクションで制御します。見たままなので、値を修正するだけなら難しくないと思います。

例えばこんな感じです。

      navbar: {
        title: 'Projmo Docs',
        logo: {
          alt: 'Projmo Logo',
          src: 'https://docs.projmo.com/img/ic_launcher.png',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'ドキュメント',
          },
          {to: '/releases', label: 'リリースノート', position: 'left'},
          {
            href: 'https://projmo.com',
            label: 'Projmo',
            position: 'right',
          },
        ],
      },

サイドバー

サイドバーは2階層の構造になっています。 1階層目に相当するカテゴリーディレクトリに、_category_.jsonファイルを作成し、そこのlabel、position、descriptionを修正すればおしまいです。 2階層目は.mdファイルの最初のセクション(#)のタイトルがそのまま使われます。

カテゴリーディレクトリはdocs/の下にいくつでもつくれます。ディレクトリを作成し、_category_.jsonファイルを作成するだけで認識されます。

カテゴリー

1階層目のメニューを選択すると、_category_.jsonファイルで指定したdescriptionと、ドキュメントの一覧が表示されます。おそらく修正することもできますが、何も問題なかったので、Projmoではそのまま使いました。

ドキュメント

何も考えずにカテゴリーディレクトリに.mdファイルを放り込むだけです。ドキュメントごとの画像ファイルは各カテゴリーディレクトリの下のimg/に置きます。

.mdファイルの先頭に以下の記述を加えると、サイドバーでの表示順番を制御できます。かんたんですね。

---
sidebar_position: 4
---

ブログ

ブログのデフォルトのパスは/blogですが、docusaurus.config.jsファイルのpresetsセクションで変更できます。

blog: {
          routeBasePath: '/releases',

navbarセクションの設定も変えておきます。

          {to: '/releases', label: 'リリースノート', position: 'left'},

authors.ymlファイルに執筆者の定義があるので修正しておきます。あとは、.mdファイルをつくっていくだけです。記事ごとにディレクトリをつくっていくとよいかもしれません。

記事の先頭に以下のメタデータを入れるとURLなどが制御できます。

---
slug: 1
title: 1st Release
authors: [yosuke]
tags: []
---

HAROLABO Tech Blog

テクノロジーを使いやすく！ハロラボの技術情報発信メディアです。

Docusaurusでドキュメントサイトを構築する