現在会社ではドキュメントをRedmineのWikiで管理しているのですが、個人的に静的サイトジェネレータの類でやりたいなぁ。と思ったのでDocusaurusというFacebook製のドキュメント生成ツールを試してみたメモ。

なんでDocusaurus


私はこのサイトでHexoを使っていて、ぶっちゃけHexoを使うのがスキルセット的に最もはやくできるのですが、いろんな公式サイトでドキュメント生成に使用されているとはいえ、Hexoはそもそもブログ特化というのとHexo以外のものも触っとくか。というので別の静的サイトジェネレータを試してみることにしました。

じゃあ、そうなったときにドキュメント特化の静的サイトジェネレータはなんやねん。という話でして、私が知っている限りでは下記の3つがあります。

で、このうちまずGitBookですがGitHubのREADMEに「GitBook.comに注力してるのでCLI版は長らく開発していません。」と書かれており、オンプレで使うには厳しいかなぁ。という判断。

次にVuepressは会社ではVueをメイン使っていて、若干おなか一杯感があるので、それならReactベースのDocusaurusを使ってみようかな。という判断です。Who is Using Docusaurus?で有名なツールでも多数採用実績があるのも大きな理由です。

環境


Docusaurus 1.7.2

インストール


公式ドキュメント通り。npmのバージョンとか要件があるので注意です。npxでインストールできる。

1
npx docusaurus-init

グローバルインストールの場合はnpm install --globalでもよいです。

1
npm install --global docusaurus-init

ディレクトリ名の変更とサーバ起動


公式ドキュメントのとおりにdocs-examples-from-docusaurusdocsblog-examples-from-docusaurusblogに変更します。それぞれdocs・blogでないとローカルで起動したときにエラーがでる。これはおそらく後から変更できるのだと思うのだけど、今回は動かすことが目的なのでこれで行くこととします。

後はdocusaurus-startでローカルで起動できます。localhost:3000にアクセスすると下記のような崩れた恐竜のアイコン(なんで??)が散らばっている画面が表示されます。

各ディレクトリとかファイルとか


docs

ドキュメントは全部ここに入れるようです。後述する設定ファイルでどのドキュメントをヘッダに表示するかとかマッピングするようになってます。

website/blog

ブログ用のコンテンツはここに格納するようです。2019-01-01-new-year.mdみたいにYYYYMMDDをハイフンで区切ったファイル名にします。URLはlocalhost:3000/blog/2019/01/01/new-yearというふうになります。

YYYYMMDD自体をディレクトリで区切る2019/01/01/new-year.mdというのはダメでした。現時点ではドキュメントにもその旨が書いてあります。ここに格納するコンテンツ量が多くなる場合はむかないと思います。そのうちできるようになるのでしょうか?

ちなみにこのディレクトリ内に入っているデフォルトのマークダウンファイルのFrontMatterを見ると下記のようになっていて、複数人での編集とソーシャルでの連携が意識されているのがわかります。

1
2
3
4
5
6
---
title: New Version 1.0.0
author: YoshinoriN
authorURL: http://twitter.com/yoshinorin24
authorFBID: 999999999
---

website/pages

サブディレクトリのトップページを書くようです。例えばtestというディレクトリを作成してlocalhost:3000/testにアクセスするだけでは何も表示されませんがen/index.jsをtestディレクトリ配下にコピーして再度アクセスすればlocalhost:3000にアクセスしたときと同じコンテンツが表示されます。中身はjs(React)で書く必要があるようです。

website/siteConfig.js

サイト全体の設定が書いてある。例えばヘッダーのリンクのマッピングとかもこの辺りでやってる。

1
2
3
4
5
6
headerLinks: [
{doc: 'doc1', label: 'Docs'},
{doc: 'doc4', label: 'API'},
{page: 'help', label: 'Help'},
{blog: true, label: 'Blog'},
],

ファイル作成


こういう静的サイトジェネレータはだいたいファイルの作成コマンドとかがあるのですが、どうにもないっぽいです。「自分でファイル作成してね」というスタンスのようです。

Docker


docusaurus-initでインストールした際に、DockerFileなどもローカルにできあがるのがわかります。が、これは普通に静的サイトを生成するだけだと使わないようです。要するにサーバ起動してサイト構築したいとき向けのようです。

生成


下記のコマンドで生成できます。

1
npm run build

website/build配下に生成されます。

その他


ローカルでサーバ上げてる途中でディレクトリ足したりしたらエラーとかでて落ちる。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Docusaurus server started on port 3000
events.js:167
throw er; // Unhandled 'error' event
^

Error: ENOENT: no such file or directory, watch 'C:\Users\YoshinoriN\site\_docusaurus\website\pages\新しいフォルダー\'
at FSWatcher.start (internal/fs/watchers.js:165:26)
at Object.watch (fs.js:1251:11)
at Gaze._watchDir (C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\gaze.js:314:30)
at C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\gaze.js:387:10
at iterate (C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\helper.js:69:5)
at C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\helper.js:78:11
at C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\gaze.js:452:5
at iterate (C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\helper.js:69:5)
at C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\helper.js:78:11
at C:\Users\YoshinoriN\site\_docusaurus\website\node_modules\gaze\lib\gaze.js:452:5

感想


まあ、この手のものは大体似たようなもんなのですぐ使えますね。細かいことはやらずにドキュメント生成を手軽に行うことに主軸を置いている感じがします。こういうのは好感が持てますね。触った感じ結構良さそうで、ちょっと個人でも利用したいなあと思っているので会社で使う前にしばらく個人で試してみようと思います。しかしdocusaurusのコマンドが長くてツライ…