Docusaurus を Docs-only mode で利用して GitHub Pages でデプロイする

posted at 2023/07/18

社内で Markdown で管理してた簡単なドキュメントを GitHub Pages でデプロイするというのを今回は Docusaurus を利用したのでそのメモを残す。

Docs-only mode とは

Docusaurus は、https://docusaurus.io/docs/installation#project-structure にもあるようにデフォルトでは以下のように、ドキュメント ( docs ) の機能とブログ ( blog ) の機能が利用できる。

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

しかし今回自分は、ブログの機能が必要ではなかったので https://docusaurus.io/docs/docs-introduction#docs-only-mode に紹介されているようにドキュメントのみの機能の設定をした。

設定内容

docusaurus.config.js に様々な設定が書かれていて、以下のような設定をした上で

module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        routeBasePath: '/', // Serve the docs at the site's root
        path: 'pages', // /docs は、 GitHub Pages で利用するので変える
        /* 他の doc にまつわる設定 */
      },
      blog: false, // ブログ機能を完全にオフにする
      // ...
    },
  ],
};

以下のようなコマンドで docs に静的資材を出力するようにする

rm -rf docs && \
docusaurus build --out-dir docs && \
docusaurus serve --dir docs

※ パスの設定を変えている場合には docusaurus clear でそのディレクトリを消してくれないので注意する。

以下では細かい設定の話を補足していく

docs.routeBasePath

これを設定することでデフォルトでは、 https://example.com/docs/some-doc になってしまうところ、 https://example.com/some-doc のように docs を省略したパスにできる。

docs.path

GitHub Pages で今回は GitHub Actions を利用できない状況だったので、ブランチをデプロイする方式を選択している。
そうなると、ルートディレクトリか /docs を GitHub Pages として指定する必要があり Docusaurus の docs とかぶってしまうため pages (ここはなんでもいい) としている。

また、 docusaurus build --out-dir docs とすることで /docs 以下に静的資材を出力している。

余談

Docusaurus 以外でよく知られているツールとしては、以下がある

jekyll
Hugo

ちなみに自分の理想は、 brew install などでバイナリが手に入って

some-awesome-cli build -o doc/　XXX.md XXX.md

上記のようなコマンドでいい感じのテーマが設定された静的サイトを作って欲しいと思っているが、未だに理想のツールには出会えていない。

jekyll でいうと Ruby を入れるのがちょっと面倒だし、Hugo は、テーマを git のサブモジュールで追加して管理するのが面倒だし、 Docusaurus も Node.js であれこれしないといけないので一長一短はあれど、この中では Docusaurus が一番デフォルトのテーマが良かった。