簡単にドキュメントなどを公開するためにDocusaurus を試してみたので記録しておきます。

環境

Ubuntu20.04 on WSL2/Windows11
nodenv 利用、node 18
gitコマンドが利用可能
GitHubへsshでアクセス可能

試した手順

プロジェクト用ディレクトリを作成

mkdir mysite
cd mysite

node準備

$ nodenv install 18.16.0
Installed node-v18.16.0-linux-x64 to ...
$ nodenv local 18.16.0
$ node --version
v18.16.0

Introduction通り実施

サイト名は public にしました

$ npx create-docusaurus@latest public classic
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
...
[SUCCESS] Created public.
[INFO] Inside that directory, you can run several commands:

  `npm start`
    Starts the development server.

  `npm run build`
    Bundles your website into static files for production.

  `npm run serve`
    Serves the built website locally.

  `npm deploy`
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  `cd public`
  `npm start`

Happy building awesome websites!

最後に書いてある通り実行するとローカルでサイトが起動し、WEBブラウザでサイトが表示されます。
ソースを変更すると即座にページが変化するので動的に確認することができそうです。

サイト設定ファイルを編集

docusaurus.config.js が設定ファイルのようです。
とりあえずコメントに従って、自分のGitHub Pagesで公開する設定を記述しました。

docusaurus.config.js

const config = {
...
  url: 'https://shinsaka.github.io',
  baseUrl: '/mysite/',
  organizationName: 'shinsaka',
  projectName: 'mysite',

GitHubへpush

ここまで作成したファイル群をGitHubへpushします。
（作成したと言ってもほぼDocusaurusの自動生成ですが）

$ git push origin main

サイトデプロイ

npm run deploy コマンドを実行し、GitHub Pagesへデプロイしてみます。
ログがたくさん表示され、自動的に色々なことをやっているようです。

いくつか拾ってみると、下記のようなことをしていると思われます。

gh-pages ブランチを作成
静的コンテンツを作成する「build」処理を実行（実際にbuildフォルダが作成されます）
GitHubへ gh-pages ブランチをpush
GitHub Pagesの設定

$ npm run deploy

> public@0.0.0 deploy
> docusaurus deploy

[INFO] Deploy command invoked...
[INFO] organizationName: shinsaka
[INFO] projectName: mysite
[INFO] deploymentBranch: gh-pages
[INFO] Remote repo URL: git@github.com:shinsaka/mysite.git
868a20be8a98b957a539cdc7d55cad362c0f2f7c
[INFO] `git rev-parse HEAD` code: 0
[INFO] [en] Creating an optimized production build...
...
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
Cloning into '/tmp/mysite-gh-pagesZii0my'...
warning: Could not find remote branch gh-pages to clone.
fatal: Remote branch gh-pages not found in upstream origin
[INFO] `git clone --depth 1 --branch gh-pages git@github.com:shinsaka/mysite.git "/tmp/mysite-gh-pagesZii0my"` code: 128
Initialized empty Git repository in /tmp/mysite-gh-pagesZii0my/.git/
[INFO] `git init` code: 0
Switched to a new branch 'gh-pages'
[INFO] `git checkout -b gh-pages` code: 0
[INFO] `git remote add origin git@github.com:shinsaka/mysite.git` code: 0
[INFO] `git add --all` code: 0
[gh-pages (root-commit) 90ddc17] Deploy website - based on 868a20be8a98b957a539cdc7d55cad362c0f2f7c
 87 files changed, 961 insertions(+)
...
 create mode 100644 index.html
 create mode 100644 markdown-page/index.html
 create mode 100644 sitemap.xml
[INFO] `git commit -m "Deploy website - based on 868a20be8a98b957a539cdc7d55cad362c0f2f7c"` code: 0
remote: Resolving deltas: 100% (29/29), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/shinsaka/mysite/pull/new/gh-pages
remote:
To github.com:shinsaka/mysite.git
 * [new branch]      gh-pages -> gh-pages
[INFO] `git push --force origin gh-pages` code: 0
Website is live at "https://shinsaka.github.io/mysite/".

確認

最後に出力されているURLへアクセスすると、Docusaurusのデフォルトサイトが公開されていることが確認できます。

GitHub Pagesの設定

GitHub設定ページの状態を確認してみます。
gh-pages ブランチのrootディレクトリを公開する設定になっているようです。

Docusaurusで静的サイトを構成してGitHub Pagesで公開する

環境