Docusaurusでマニュアルを作る #3 コンテンツ作成 — コードブロック、Mermaid、admonition

フレームワーク Docusaurus Documentation Static Site
読了 3分

#2でサイドバーと検索を使ってドキュメントの骨組みを組みました。今度はその中を埋める番です。技術ドキュメントは文章だけでは足りません。コマンドはコードブロックで、流れはダイアグラムで、注意すべき点は目立つ箱で見せてこそ、読者は素早く読めます。

今回のシリーズはDocusaurusでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 サイドバーと検索 — ドキュメントの情報構造を組む
  • #3 コンテンツ作成 — コードブロック、Mermaid、admonition ← 今回の記事
  • #4 Cloudflare Pagesでデプロイしてドメインを接続する
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

今回の記事はコードブロックをきちんと装飾し、Mermaidでダイアグラムを描き、admonitionで強調するという三つを扱います。Docusaurusはこれらの機能のほとんどを標準で備えており、有効にするものが少ないです。

コードブロック — タイトルと行強調 #

Docusaurusはコードのハイライトとコピーボタンを標準で提供します。コードフェンスの言語の後ろにオプションを記述して、タイトルと強調を加えます。

コードブロックにタイトルと強調 
```js title="src/app.js" {2}
function add(a, b) {
  return a + b; // この行が強調されます
}
```

titleでファイル名の帯を、{2}のように波括弧の中の数字で強調する行を指定します。コピーボタンはすべてのコードブロックに自動的に付きます。

ダイアグラム — Mermaid #

Mermaidは別途テーマパッケージを追加して有効にします。パッケージをインストールした後、docusaurus.config.jsで有効化します。

docusaurus.config.js — Mermaid有効化 
export default {
  markdown: { mermaid: true },
  themes: ['@docusaurus/theme-mermaid'],
};

これでmermaidフェンスを開けば、実際のダイアグラムとしてレンダリングされます。

Mermaidフローチャート 
```mermaid
flowchart LR
  A[記事作成] --> B[ビルド] --> C[デプロイ]
```

admonition — 注意と警告の強調 #

「これは必ず読まなければならない」という内容は、文章の間に埋もれてはいけません。Docusaurusはadmonitionを標準で内蔵しています。コロン三つで囲み、後ろに種類を記述します。

admonitionの書き方 
:::warning 注意
本番に適用する前に、必ずバックアップを先に取ってください。
:::

種類にはnote、tip、info、warning、dangerがあり、それぞれ色とアイコンが違うため、情報・注意・危険を視覚的に区別できます。

タブで分ける #

Docusaurusの強みは、マークダウンの中でReactコンポーネントを使えるMDXです。OSごとのコマンドのように枝分かれする内容は、Tabsコンポーネントで見せます。

タブで分ける 
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="mac" label="macOS">brew install our-product</TabItem>
  <TabItem value="win" label="Windows">winget install our-product</TabItem>
</Tabs>

まとめ #

今回の記事では、タイトルと行強調が付くコードブロック、コードで管理するMermaidのダイアグラム、そして注意・警告を強調するadmonitionとタブまで扱いました。ほとんどが内蔵なので設定が少なく、MDXのおかげで表現の天井が高いという点がDocusaurusの強みです。

次回はこのドキュメントを世に送り出します。Cloudflare Pagesでデプロイしてカスタムドメインを接続し、誰でもアドレスでアクセスできるようにする過程を整理します。

X