mdBook の使い方

mdBook は Rust 製の静的サイトジェネレーターで、Markdown ファイルからドキュメントサイト（HTML）を生成します。このリポジトリで使っているツールです。

インストール

Rust がある場合（推奨）

cargo install mdbook

バイナリを直接取得する場合

GitHub Releases から OS に合ったバイナリをダウンロードして PATH の通ったディレクトリに置きます。

Windows（winget）

winget install -e --id Rust.Rust
cargo install mdbook

プロジェクト構造

book.toml       # プロジェクト設定
src/
  SUMMARY.md    # 目次（章の順序と構成を定義）
  chapter_1.md  # 記事ファイル
book/           # ビルド出力（自動生成・編集不要）

book.toml の主要設定

[book]
title = "APAC-HPC-AI"
authors = ["Typewriter"]
language = "ja"          # サイトの言語コード

[build]
build-dir = "book"       # 出力先ディレクトリ（デフォルト: book）

SUMMARY.md — 目次の書き方

src/SUMMARY.md が本全体の構成を決定します。ここに書いたリンクのみがサイドバーに表示されます。

# Summary

- [はじめに](./introduction.md)

# 第1部：ツールガイド
- [mdBook の使い方](./mdbook-usage.md)
- [GitHub Pages への公開](./github-pages.md)

# 第2部：OpenFOAM
- [OpenFOAM 入門](./openfoam/intro.md)
  - [メッシュ生成](./openfoam/meshing.md)   ← インデントでサブ章

ルール:

  • リストアイテム - [タイトル](./ファイルパス) が章になる
  • インデント（2スペース or タブ）でサブ章を作れる
  • # 見出し はセクション区切り（リンクなし）
  • SUMMARY.md に書かれていないファイルはサイトに含まれない

記事の書き方

src/ 以下に .md ファイルを作成します。通常の Markdown がそのまま使えます。

# 章タイトル

## セクション

本文テキスト。**太字**、*斜体*、`コード` が使えます。

コードブロック（シンタックスハイライト付き）:

​```bash
mpirun -np 4 openfoam
​```

数式（KaTeX）:

\\( E = mc^2 \\)    ← インライン数式

\\[
  \nabla \cdot \mathbf{u} = 0
\\]                  ← ブロック数式

ディレクトリで章をまとめる

src/
  openfoam/
    intro.md
    meshing.md

SUMMARY.md でのパス指定: ./openfoam/intro.md

ビルドとプレビュー

コマンド説明
mdbook buildbook/ に HTML を生成
mdbook serveローカルサーバーを起動（http://localhost:3000）
mdbook serve --openブラウザも自動で開く
mdbook watchファイル変更を監視して自動ビルド（サーバーなし）
mdbook cleanbook/ を削除

mdbook serve 実行中はファイルを保存するたびにブラウザが自動更新されます。

新しい章を追加する手順

  1. src/ にファイルを作成する
# 例: OpenFOAM 入門記事
# （Windowsの場合）
New-Item src/openfoam-intro.md
  1. src/SUMMARY.md にリンクを追加する
- [OpenFOAM 入門](./openfoam-intro.md)
  1. mdbook serve で確認する

この 2 ステップを忘れると、ファイルを作ってもサイトに表示されないので注意。

カスタマイズ（book.toml）

[book]
title = "APAC-HPC-AI"
description = "APAC HPC-AI Competition 2026 チーム知識ベース"

[output.html]
theme = "navy"               # デフォルトテーマ: default, rust, coal, navy, ayu
git-repository-url = "https://github.com/<username>/APAC-HPC-AI"
edit-url-template = "https://github.com/<username>/APAC-HPC-AI/edit/main/{path}"

[output.html.search]
enable = true    # 全文検索（デフォルトで有効）

edit-url-template を設定すると各ページに「ページを編集」リンクが表示され、共同執筆がしやすくなります。