Docusaurusを使ってマークダウンで簡単にwebサイトを作ってみた

はじめに

本記事はDocusaurusを使用してドキュメントを作り、GitHub Pagesに公開するまでをまとめた記事です。
Docusaurusとは簡単にいうと、マークダウンで作成した文書からいい感じの見た目のサイトを生成してくれるツールです。
マニュアルやブログなどドキュメントサイトを生成するのに適しています。
DocusaurusにはV1とV2がありますが、V2の使用が推奨されていましたので、本記事でもV2を扱います。
本記事は、Version: 2.0.0-beta.9時点での動きになります。
また、今回はDocusaurusの機能のDocsを利用します。PagesやBlogsは利用しません。 これは、公式にはDocs-only modeと呼ばれています。

Docusaurusのインストール

最初にNode.js(Ver.14以上)とYarn(1.5以上)が無い方はインストールしておきます。

次にDocusaurusをインストールします。
ターミナルで作業フォルダまで移動します

cd 作業フォルダのパス

ターミナルで以下のコマンドを入力しインストールします。
[name]はフォルダ名になります。[name]で指定した名前のフォルダが作業フォルダに作成され、その下にDocusaurusがインストールされます。
[template]にはDocusaurusのテンプレート名を入力します。classicと入力することが推奨されています。

npx create-docusaurus@latest [name] [template]

例えば、以下のようなコマンドを実行します。「website」というところは任意で変えてください。

npx create-docusaurus@latest website classic

インストールが完了したら以下のコマンドでwebsiteフォルダに移動しサイトが立ち上がるか確認します。

cd website
npm start

ローカルにウェブサーバーが立ち上がり、http://localhost:3000でサイトが表示されます。（Ctrl+Cで停止できます。）
この間にwebsiteフォルダ以下のファイルを変更すると、ブラウザがリロードされ、表示が更新されます。

サイトのホームページを変更

今回は冒頭でも述べたようにブログや他ページの無い、シンプルなドキュメントのみのページを作成しようと思うので、サイトのホームページをdocsフォルダ以下にする必要があります。

まずはdocusaurus.config.jsを開き、presetsの配下のdocsの配列に、以下を追加します。

routeBasePath: '/',

presets配下の全体像は以下のようになります。

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          routeBasePath: '/',
          // Please change this to your repo.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

docsフォルダにホームページ用のマークダウンファイルを作成し、URLを指定するslugを追加します。
例えば、website\docs\home.mdファイルを作成し、home.mdの先頭に以下を追加します。

---
slug: /
---

そして、元々のホームページである、src/pages/index.jsを削除した後、http://localhost:3000/にアクセスすると、先ほど設定したwebsite\docs\home.mdが表示されます。

ドキュメントをカスタマイズする

docs配下にデフォルトであるフォルダやファイルは削除して構いません。
サイトに表示したいマークダウンファイルをdocs配下に格納すればOKです。
サイドバーに表示される名前、階層構造、表示順などのカスタマイズは以下のように行えます。

サイドバーに表示する名前を変更する

サイドバーに表示される名前は特に指定しなくても以下のパターンで設定されます。

• マークダウンファイルの1番上の見出しが#1個で始まっていれば、その見出しが表示される
• 1番上の見出しが#1個でなければファイル名がサイドバーに表示される。

上記のような決め方ではなく、個別に決めたい場合はファイルの先頭に以下を追加します。

---
title: ここに任意のタイトルを入力
---

サイドバーに階層構造を作る

サイドバーに階層構造を作成したいときは、docs配下に任意の名前でフォルダを作成するだけです。
フォルダ名がそのままサイドバーに表示され、フォルダ配下のファイルがその子要素としてツリー構造で表示されます。
名前を指定したい場合は、そのフォルダの中に_category_.jsonというJsonファイルを作成します。
以下のようにlabelに表示名、positionに表示順を指定することでカスタマイズできます。

{
    "label": "フォルダ1",
}

サイドバーの表示順を指定する

サイドバーの中の表示順を指定するには、マークダウンファイルの先頭にsidebar_position: を追加します。
例えば、ホームページとなるマークダウンはサイドバー上で先頭に表示されてほしいため、以下をマークダウンファイルの先頭に追加します。

---
slug: /
sidebar_position: 1
---

フォルダの表示順は、上記で出てきた_category_.jsonというJsonファイルに"position": を追加します。
例えば、以下のようになります。

{
    "label": "フォルダ1",
    "position": 2
}

ヘッダーやフッターを変更する

ヘッダーやフッター、ロゴ画像は、docusaurus.config.jsのthemeConfigを編集することで変更できます。
ヘッダーのナビバー部分はnavbarを編集します。
今回、ブログや他ページを用意しないため、Itemsは不要かと思うので、削除します。
ここを削除すると、ヘッダー部分に余分なアイテムが配置されなくなります。
また、titleやlogoを任意に変更します。例えば、navbarを以下のように変更します。

      navbar: {
        title: 'サンプルサイト',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
      },

すると、ヘッダー部分は以下のように表示されます。

フッターは、ヘッダーと同様footerやcopyrightを編集することで変更できます。

GitHubPagesに公開する

サイトの編集ができたので、デプロイしたいと思います。
今回はGitHub Pagesを使用します。

まずは、ビルドのテストするために、以下をターミナルで実行します。

npm run build

ビルドが成功したら以下を実行します。

npm run serve

http://localhost:3000/にアクセスできるか試します。
テストが終わったら、いよいよデプロイ作業です。docusaurus.config.jsのurl、baseUrl、organizationName、projectNameを編集して、デプロイするリポジトリを設定します。
以下のように編集します。{ }の部分は置き換えてください。

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://{リポジトリのオーナー名}.github.io/',
  baseUrl: '/{リポジトリ名}/',
  onBrokenLinks: 'warn',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: '{リポジトリのオーナー名}', // Usually your GitHub org/user name.
  projectName: '{リポジトリ名}', // Usually your repo name.

その後、以下のコマンドを実行します。バッシュ、ウィンドウズ、パワーシェルでコマンドが異なるので詳しくはこちらをご覧ください。
<GITHUB_USERNAME>はリポジトリのオーナー名に置き換えます。

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

これで、リポジトリにgh-pages ブランチが作成されて、ビルドしたファイルだけがgh-pagesブランチに展開されていれば成功です。
次に、Github pages を有効にします。
デプロイ先のリポジトリのSettingsのPagesを見に行きます。
Sourceでブランチをgh-pagesにして、File:/(root)に設定し、Saveを押すと有効になります。
今後は青枠で囲ったところのUrlから誰でも作成したサイトにアクセスすることができます。
私の場合、UrlからはSaveを押した2,3分後にサイトが表示されるようになりました。Saveの直後にUrlにアクセスしても404と表示される可能性がありますので、少し待ってから試してみてください。

さいごに

自分でHTMLやCSSを書かなくて、ほぼマークダウンだけでいい感じにサイトを生成してくれ、さらに、デプロイのコマンドまで用意してあるので、webページの知識が無くてもすごく簡単に公開までできてしまうのがすごいと思いました。
最後までお読みいただきありがとうございました。
次回はGitHubでマークダウンをコミットするたびにサイトが更新されるよう、GitHub Actionsの設定についてまとめます。