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

フレームワーク Hugo Documentation Static Site
読了 4分

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

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

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

この記事では コードブロックをきちんと整え、Mermaid でダイアグラムを描き、コールアウトで強調する という三つを扱います。すべて標準マークダウンに Hextra が乗せてくれる機能です。

コードブロック — ファイル名と行ハイライト #

最も基本なのは、フェンスで囲んだコードブロックです。これに Hextra がいくつかの機能を加えてくれます。コードフェンスの言語のあとに波括弧でオプションを書きます。

コードブロックにファイル名を付ける 
```js {filename="main.js"}
console.log("hello");
```

このように書くと、コードブロックの上に main.js というファイル名の帯が付きます。どのファイルのコードかが一目で分かるので、複数のファイルを行き来する説明では特に役立ちます。

特定の行をハイライトしたり、行番号を付けたりもできます。

行ハイライトと行番号 
```py {filename="app.py",hl_lines=[2],linenos=table}
def add(a, b):
    return a + b  # この行がハイライトされます
```

hl_lines でハイライトする行を、linenos=table で行番号を指定します。コピーボタンは Hextra がすべてのコードブロックに自動で付けてくれるので、別途手を入れることはありません。

ダイアグラム — Mermaid #

アーキテクチャや流れを説明するときに画像を直接描き入れると、あとで修正するたびに画像ファイルを作り直さなければなりません。Mermaid はダイアグラムを コードで 書きます。テキストなので Git でバージョン管理ができ、直すのも簡単です。mermaid 言語でフェンスを開けばよいです。

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

Hextra はこのブロックをビルド時に実際のダイアグラムとしてレンダリングします。フローチャートだけでなく、シーケンス図、クラス図、ガントチャートなど、Mermaid がサポートする形式をそのまま使えます。

コールアウト — 注意と警告の強調 #

「これは必ず読んでほしい」という内容は、地の文の中に埋もれてはいけません。Hextra は callout ショートコード(shortcode)で強調ボックスを提供します。

コールアウトを使う 
{{< callout type="warning" >}}
本番に適用する前に、必ずバックアップを先に取ってください。
{{< /callout >}}

type には info、warning、error を与えられ、省略すると既定のグレーのボックスになります。タイプごとに色とアイコンが異なるので、情報・注意・危険を視覚的に区別できます。

参考までに、上の例のようにショートコードをコードブロックの中に そのまま見せるには、Hugo のエスケープ表記 {{< >}} を使う必要があります。普通に書くと Hugo がショートコードを実行してしまい、コード例ではなく本物のコールアウトがレンダリングされます。ドキュメントを書いていてよく踏む落とし穴なので、#6 で改めて整理します。

その他のブロック — タブとステップ #

長い説明を畳んだり、OS ごとに分けて見せたりするときはタブが便利です。

タブで分ける 
{{< tabs items="macOS,Windows" >}}
  {{< tab >}}brew install ...{{< /tab >}}
  {{< tab >}}winget install ...{{< /tab >}}
{{< /tabs >}}

インストールのように順序が重要な手順は、steps で番号を振って見せられます。これらのショートコードは Hextra に標準で内蔵されているので、追加インストールなしですぐに使えます。

まとめ #

この記事では、ファイル名と行ハイライトが付くコードブロック、コードで管理する Mermaid のダイアグラム、そして注意・警告を強調するコールアウトを扱いました。ここまで来ると、ローカルで見やすいドキュメントが整います。

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

X