facebookが開発しているDocusaurusを利用すると、Markdownを書いてちょちょいと設定すればナウい感じのドキュメントを作成することができるという噂を聞きつけ、今回はインストールから簡単な設定を行い、GitHub Pagesへ公開するところまでを駆け足でたどります。
具体的な事例は公式サイトに一覧が掲載されていますが、facebook製だけあってReact関連のプロジェクトはほとんどがDocusaurusみたいですね。
なおDocusaurusには現行バージョンの1.x系と、開発中の2.x系がありますが、今回は1.x系を利用します。2系はコマンドや設定が異なりますのでご注意ください。
とりあえず初めてみる
インストール
Node.jsの10.9.0以上がインストールされている環境で以下のコマンドを実行します。
$ npm install -g docusaurus-init
必要なインストールや初期設定は以上です。
初期ファイルを作成
適当なディレクトリを作成し、中に移動したらdocusaurus-initコマンドを実行すると、テンプレート的な初期ファイルが自動生成されます。
$ mkdir foo; cd foo $ docusaurus-init
最終的に生成されたファイルがtreeコマンドのように表示されます。
foo
├── Dockerfile
├── docker-compose.yml
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ ├── exampledoc4.md
│ └── exampledoc5.md
├── package.json
└── website
├── README.md
├── blog
│ ├── 2016-03-11-blog-post.md
│ (中略)
│ └── 2017-10-24-new-version-1.0.0.md
├── core
│ └── Footer.js
├── package-lock.json
├── package.json
├── pages
│ └── en
│ ├── help.js
│ ├── index.js
│ └── users.js
├── sidebars.json
├── siteConfig.js
└── static
├── css
│ └── custom.css
└── img
├── favicon.ico
(中略)
└── undraw_youtube_tutorial.svg
実行する
websiteフォルダに移動し、npm startすると確認用のサーバ3000番のポートで起動します。
$ cd website $ npm start
自動的にWebブラウザで次のようなページが開きます。このあとファイルを編集していきますが、元となるファイルを修正すると自動的にリロードされます。超便利。
確認用のサーバを停止するときはCtrl+cで強制的に終了させます。
編集してみる
サイト名
「website」フォルダの下にいる「siteConfig.js」を開いてみます。このファイルはサイトの基本的な定義がまとめられているようです。この中のsiteConfig.titleの値をTest SiteからAwesome Siteに変更し保存してみます。
Webブラウザに戻ると自動的にリロードされ、先ほど編集した内容に変わっているのがわかります。おお、ちょっと感動したｗ
テーマカラー
デフォルトの配色はdocusaurus-initする度にランダムに決定されるそうで、配色ガチャに見事当たればよいのですがまぁそううまくはいきませんｗ
というわけでwebsite/siteConfig.jsの以下の箇所でテーマカラーを変更できます。濃い方の色をprimaryColorにした方がまとまりが良いです。
/* Colors for website */ colors: { primaryColor: '#4b1475', secondaryColor: '#340e51', },
色を自分で決めるのが難しい場合は、配色ツールを利用すると便利ですね。
ドキュメントを編集する
docs/doc1.mdを編集してみます。
オリジナルのファイルは「docs」フォルダの下にいますので、今回は「doc1.md」をテキストエディタなどで開きタイトル部分を編集しました。
これも保存した瞬間にブラウザが自動的にリロードされ、編集した箇所が置き換わってくれます。
お分かりかと思いますが、現在ブラウザに表示されているのは「website」フォルダから下にあるファイルですが、これはオリジナルである「docs」から自動的に生成された物です。Docusaurusが「docs」フォルダを監視し、ファイルが更新されたら「website」フォルダへ自動生成されますので、編集する際には必ずオリジナルのファイルを触る必要があります。
ページを追加する
ドキュメント
「docs」フォルダの下に新しい記事docs/doc6.mdを追加します。本文にはもちろんMarkdownが使えます。
--- id: doc6 title: 新しく追加したよ --- やあ、ジョージィ！ ここに本文を書くんだよ。
次にwebsite/sidebars.jsonを開き、先ほど追加したMarkdownのidを適当な場所に書いてあげます。ここではJSONのdocsの中に新しくNew Categoryというラベルを追加しそこからリンクさせることにしました。
{ "docs": { "Docusaurus": ["doc1"], "First Category": ["doc2"], "Second Category": ["doc3"], "New Category": ["doc6"] }, "docs-other": { "First Category": ["doc4", "doc5"] } }
npm startで確認用サーバを動かしている場合は、一度Ctrl+cで終了させもう一度起動します。するとJSONで指定したとおりに追加されました。
ブログ
ブログの場合はwebsite/blogの下にファイルを追加します。ここではwebsite/blog/2020-09-04-hello.mdとして以下の内容を保存しました。ファイル名のネーミングルールはYYYY-MM-DD-(ファイル名).mdとする必要があります。
--- author: Makito Katsube authorURL: https://blog.katsubemakito.net/ authorFBID: 1265449499 title: こんにちは！こんにちは！ --- こんにちは。かつべです。 <!--truncate--> ここから先は一覧ページでは表示されず、個別ページで閲覧できます。
あとは確認サーバが自動的に反映してくれます。
facebook製のツールなだけはあってauthorFBIDにfacebookのユーザーIDを書くと、facebookで利用しているアイコンが自動的に挿入されます。facebookのユーザーIDの確認方法は、PC版のfacebookにログインしたら上部のバーにある自分の名前をクリックしプロフィールページへ移動、「タイムライン」をクリックするとURLに現れるlst=から%3Aの間にある数字です。
とは言え、facebookやってないとか、facebookのアカウントを晒したくないといった場合にはauthorFBIDの代わりにauthorImageURLを記述しURLを書けば好きな画像が埋め込めます。
GitHub Pagesで公開する
DocusaurusはGitHub Pagesと親和性が高い作りになっており、一度設定してしまえばコマンド一発でアップできます。
設定
まず最初にwebsite/siteConfig.jsを開き公開設定を行います。
const siteConfig = { url: 'https://katsube.github.io/', // GitHub PagesのURL("katsube"の箇所は自分のユーザー名) baseUrl: '/testProject/', // GitHub Pagesのパス(projectNameと合わせる) projectName: 'testProject', // サイト名 organizationName: 'katsube', // GitHubのユーザー名(または組織名) }
GitHub上にリポジトリを作成
website/siteConfig.jsのsiteConfig.projectNameで指定した文字列と、同じ名前のリポジトリを作成します。「公開」「非公開」どちらの設定でもかまいません。また現時点では空のままでOK。SSHでgit cloneやgit pushなどが行えるようにログイン周りの設定も行っておいてくださいね。
最終的に以下のようにGitHub Pagesとの関連付けの設定が行われ、ビルドしたファイルがそのままアップロード(push)されます。
このステップがドキュメントから読み取れなくてめっちゃ時間を消費しましたｗ
ビルド
最終的に公開するファイルを作成するために「ビルド」を行います。ビビらなくて大丈夫、コマンドを1発実行するだけですw「website」フォルダへ移動し以下のコマンドを実行します。
$ npm run build
すると「website」内に「build/(projectName)」フォルダが新たに作成されます。この下に生成されたファイルを自前のWebサーバやGitHub Pagesなどにアップします。
ビルド時に何をやっているかと言うと、Markdownを静的なHTMLファイルに変換するのはもちろんですが、Reactで作成されている部分を古いブラウザでも動くようBabelで古い構文に変換したり、不要なホワイトスペース（半角スペースや改行）などのお掃除してくれているようです。
アップロード
最初にシェルの環境変数を設定します。このあたりはシェルスクリプトとしてファイルに纏めておいても良いかもしませんね。GIT_USERで指定している箇所は自分のGitHubのアカウント名に置き換えてください。
$ export GIT_USER=katsube $ export CURRENT_BRANCH=master $ export USE_SSH=true
その後、「website」フォルダの直下で以下のコマンドを実行します。
$ npm run publish-gh-pages
するとGitHub Pagesに無事に公開されました！
まとめ
思ったより面倒でしたｗ とは言え最初にガリッと設定してしまえば、あとはひたすらMarkdownを書く作業に集中できそうなので、最初のハードルを乗り越えられるか…ですかね。
また2系ではテーマ機能も入るみたいで、デザインが簡単に切り替えられるようですね。早く正式リリースされないかなぁ。
