Docusaurus

Docusaurus は、ドキュメントに特化した Web アプリケーションフレームワークです。次のような特徴を持っています。

.md または .mdx（JSX を含む Markdown）で書ける。
フォルダ構造がそのまま記事の階層構造になる。
簡単なフラグ切り替えで、サイドバーやナビゲーションバーの挙動・内容をカスタム可能。
ドキュメント（docs）以外にも、ページ（page）、ブログ（blog）をサイト内で組み合わせることが可能。それぞれページ内の機能が異なる。
最適化の施された静的サイトジェネレーターであり、ページの読み込みが早い。

本ページでは、ドキュメントの作り方に絞って記述します。

始める前に

Node が必要です。バージョンは適時調べて下さい。

サイトを作る

npx create-docusaurus@latest サイト名 classic

サイトをローカルで動かす

npm start

記事を書く

記事を書くには、/docs/ 以下に .md を追加します。記事はフォルダと同じ構成で生成され、ファイルの先頭に次のようなエリアを置くことで、挙動をカスタマイズできます。（内容は公式リファレンスより）

---
id: doc-with-tags
title: A doc with tags
tags:
  - Demo
  - Getting started
slug: /bonjour
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---

_category_.json

記事のフォルダに _category_.json を置くと、その親の表示内容を指定できます。

{
  "label": "親のタイトル",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "ページの先頭に表示されます。"
  }
}

カスタマイズ

/docusaurus.config.js を編集することで、ナビゲーションバーやサイドバーの挙動を変更できます。

このファイル内のパス（img/... など）は、/static/ を起点にしています。

読み込み時の折りたたみ状態

サイドバーの折りたたみ項目を初めから開いた状態にできます。サイドバーそのものの表示切り替えではありません。

presets: [
  // ...
  docs: {
    sidebarCollapsed: false,
  }
// ...
]

ドキュメントのみモード

Docusaurus では、「ドキュメント」のみを表示するシンプルなサイトを作ることもできます。

presets: [
  // ...
  docs: {
    routeBasePath: '/',
  },
  blog: false,
  // ...
]

加えて、トップページにしたい記事に slug を設定することで、ドキュメント以外のページが表示されなくなります。

---
slug: /
---

Vercel で公開する

Vercel は、Web サイトを簡単にデプロイしてくれる、一種のホスティングサービスです。
Vercel は Docusaurus に対応しており、GitHub 上のリポジトリと連携させれば特定のブランチが変更される度に再デプロイしてくれます。

Vercel にデプロイする方法は、アカウントを作成し、GitHub リポジトリを連携するだけです。フレームワークなどは自動的に識別されて、適切にデプロイされます。もちろん自分で選ぶこともできます。

2023年6月23日