はじめに

この文章ではmdBookで日本語の技術文書を書くためのテンプレートmdbook-ja-templateについて説明します。このテンプレートを使うことで、 Markdownの文書をHTMLに変換し、ウェブサイトとして公開できます。

特徴

mdbook-ja-templateの特徴を説明します。

すぐに執筆・発信できる

文書執筆に必要なツール一式がDockerコンテナ化されているため、面倒なセットアップ作業は不要です。すぐに執筆を始めることができます。

文書公開のために必要な作業がGitHub Actionsのワークフローとして定義されており、自動的に実行されます。余計な手間をかけることなく、作成した文章をすぐに発信できます。

文書校正が自動で行われる

文章校正ツールtextlintが導入されているため、文書の自動校正が可能です。初期状態で技術文書向けの校正ルールが設定されていますが、自分好みになるようカスタマイズ可能です。

Markdownのスタイルチェックツールmarkdownlintも導入されているため、Markdownの自動スタイルチェックも可能です。

コマンドを覚えなくても使える

文書校正や各種チェックツールはmake check -kを実行するだけで一括実行できるよう設定されているため、各種チェックツールのオプションを覚える必要はありません。その他にも、執筆時の典型的なタスクがMakefileで実行できるよう設定されています。

コントリビューション

mdbook-ja-templateはオープンソースプロジェクトで、ソースコードはGitHub上で公開されています。問題の報告や機能追加の要望はGitHubのIssueトラッカーに投稿してください。

ライセンス

mdbook-ja-templateはCreative Commons Zero v1.0 Universalライセンスで配布されています。

基本的な使い方

mdbook-ja-templateの基本的な使い方を説明します。本章で説明する手順に従うことで、mdbook-ja-templateを使って執筆した文章をウェブサイトとして公開できます。

事前準備

mdbook-ja-templateを利用するためには、以下のコマンドが必要です。

Docker Compose
npm (オプション)

Docker Composeのインストール方法はInstall Docker Composeを参照してください。

npmはVisual Studio Code等のエディタ・IDEとmdbook-ja-templateの各種チェック機能を連携させる場合に必要です。多くの場合Node.jsをインストールすることでnpmがインストールされます。 Node.jsのインストール方法はパッケージマネージャを利用したNode.jsのインストールを参照してください。

Gitリポジトリを作成する

mdbook-ja-templateと同じ内容のGitリポジトリを作成します。 mdbook-ja-templateはテンプレートリポジトリとして設定されているため、同じ内容のGitリポジトリを簡単に作成できます。

Gitリポジトリを作成するには、GitHubウェブサイトから作成する方法と、GitHub CLIで作成する方法があります。

GitHubウェブサイトから作成する方法

以下手順に従うことで、GitHubウェブサイトからGitリポジトリを作成できます。

Create a new repository from mdbook-ja-templateへアクセスする
表示された入力フォームへ必要事項を記入する
"Create repository from template" ボタンを押す

GitHub CLIで作成する方法

GitHub CLI (ghコマンド) を実行することでGitリポジトリを作成します。

以下はrepositoryという名前の公開リポジトリを作成する場合のコマンド実行例です。 --template https://github.com/gifnksm/mdbook-ja-template オプションが、mdbook-ja-templateを使用することを示しています。その他のオプション指定は必要に応じて追加・変更してください。

$ gh repo create \
    --template https://github.com/gifnksm/mdbook-ja-template \
    --public \
    repository
✓ Created repository gifnksm/repository on GitHub

文書情報を設定する

文章を執筆する前に、文書のタイトルや著者などの文書情報を設定しましょう。

前節で作成したGitリポジトリのbook.tomlファイルは以下のようになっています。

[book]
authors = ["gifnksm <makoto.nksm+github@gmail.com>"]
title = "mdbook-ja-templateユーザーズガイド"
language = "ja"
src = "src"
multilingual = false

[output.html]
mathjax-support = true
additional-js = ["js/mermaid.min.js", "js/mermaid-init.js"]
git-repository-url = "https://github.com/gifnksm/mdbook-ja-template"
edit-url-template = "https://github.com/gifnksm/mdbook-ja-template/edit/main/{path}"
site-url = "/mdbook-ja-template/"

[output.linkcheck]

[preprocessor]

[preprocessor.mermaid]
command = "mdbook-mermaid"

以下の設定項目を変更してください。設定項目の意味についてはmdBookのドキュメントを参照してください。

bookセクション
- authors: 著者名を設定する。複数設定する場合はカンマ区切りで記述する
- title: 文書のタイトルを設定する
output.htmlセクション
- git-repository-url: 前節で作成したGitリポジトリのURLを設定する
- edit-url-template: 前節で作成したGitリポジトリのURLの末尾に/edit/main/{path}を追加したものを設定する
- site-url: リポジトリ名を設定する

book.tomlはGitHubウェブサイト上で直接編集可能ですが、 Gitリポジトリをcloneして編集することを推奨します。以降の節ではGitリポジトリをcloneしていることを前提に説明します。

ウェブブラウザで表示を確認する

文書の設定が完了したら、ブラウザでどのように表示されるか確認してみましょう。

文書の表示を確認するためには、リポジトリのルートディレクトリで以下のコマンドを実行してください。 http://localhost:3000/でHTTPサーバーが立ち上がり、ウェブブラウザからアクセスすることで文書の表示を確認できます。

make serve

HTTPサーバー起動中に関連するファイルが変更された場合、ページがリロードされ変更後の内容が表示されます。文章の表示をリアルタイムで確認しながら執筆できるので、基本的にはHTTPサーバーを立ち上げた状態で執筆するのが良いでしょう。

HTTPサーバーを立ち上げないで表示を確認する

HTTPサーバーが不要な場合、以下のコマンドを実行してください。 book/ディレクトリ配下にHTMLファイルが生成されます。 book/index.htmlをウェブブラウザで開くことで、文書の表示を確認できます。

make build

以下コマンドを実行するとMarkdownファイルの変更を監視するプロセスが起動し、変更の度に自動でHTMLが更新されます。それ以外は同じです。

make watch

SUMMARY.mdを作る

ウェブサイトでの表示を確認したら、文書の目次となるsrc/SUMMARY.mdを作りましょう。

Gitリポジトリのsrc/ディレクトリ配下のファイルをすべて削除して、src/SUMMARY.mdを作成しましょう。

src/SUMMARY.mdの中身は以下のようになります。作成したい文章の内容に沿った目次を作成しましょう。

# Summary

[はじめに](intro.md)

- [ユーザーズガイド](guide/README.md)
  - [インストール方法](guide/install.md)
  - [使い方](guide/usage.md)
- [リファレンスガイド](reference/README.md)
  - [コマンド一覧](reference/commands.md)
  - [メッセージ一覧](reference/messages.md)

---

- [付録](appendix.md)

src/SUMMARY.mdの構造についてはmdBookのドキュメントを参照してください。通常のMarkdownファイルとは異なり、src/SUMMARY.mdでは一部のMarkdown文法しか使用できません。 src/SUMMARY.mdの内容に問題がある場合は、make serve/make watch/make buildの出力にエラーが表示されます。出力された内容に従ってファイルを修正してください。

Tips

文書執筆を楽にするテクニックを紹介します。

ドラフト

以下のようにURLが空のリンクを記載することで、該当するページがドラフトであることを示すことができます。ドラフトのページは、ウェブサイト上では灰色で表示され、src/配下にファイルは作成されません。

[ページ名]()

空のリンクはMarkdownlintのルールMD042 - No empty linksによって警告されます。警告を無効化するためには、以下をsrc/SUMMARY.mdの先頭に追加してください。

<!-- markdownlint-disable MD042 -->

サンプル

以下に、本ドキュメントのSUMMARY.mdを示します。

# Summary

<!-- markdownlint-disable MD042 -->

[はじめに](./README.md)

- [基本的な使い方](./basic_usage/README.md)
  - [事前準備](./basic_usage/preparation.md)
  - [Gitリポジトリを作成する](./basic_usage/create_git_repository.md)
  - [文書情報を設定する](./basic_usage/set_document_info.md)
  - [ウェブブラウザで表示を確認する](./basic_usage/view_document.md)
  - [SUMMARY.mdを作る](./basic_usage/create_summary.md)
  - [本文を執筆する](./basic_usage/write_document.md)
  - [文書校正する](./basic_usage/correct_document.md)
  - [ウェブサイトとして公開する](./basic_usage/publish_document.md)
  - [ウェブサイト公開後](./basic_usage/after_publish_document.md)
- [応用的な使い方](./advanced_usage/README.md)
  - [mdBookのカスタマイズ](./advanced_usage/customize_mdbook.md)
  - [textlintのカスタマイズ](./advanced_usage/customize_textlint.md)
  - [markdownlintのカスタマイズ](./advanced_usage/customize_markdownlint.md)
  - [Docker Composeの使い方](./advanced_usage/docker_compose.md)
- [リファレンス](./reference/README.md)
  - [makeターゲット一覧](./reference/make_targets.md)

本文を執筆する

src/SUMMARY.mdを作成した後は、本文となる文章を執筆しましょう。

make serveまたはmake watchを実行している場合、src/SUMMARY.mdを編集した時点でsrc/ディレクトリ配下に本文を執筆するMarkdownファイルが生成されます。これらのコマンドを実行していない場合でも、make buildを実行することでMarkdownファイルが生成されます。

Markdownファイルで使用可能なMarkdown記法についてはmdBookのドキュメントを参照してください。通常のMarkdown文法に加え、mdbook-ja-templateでは以下の機能が使用可能です。

mdBook固有機能
MathJaxによる数式の埋め込み
mermaid.jsによるフローチャート等の埋め込み

サンプル

各種機能の使用例を紹介します。

Rustコードの埋め込み

本文中にRustのコードを埋め込むことができます。コード中の実行ボタンを押すことで、コードの実行結果を表示できます。

ソースコード

```rust
fn main() {
    println!("Hello, world!");
}
```

表示結果

fn main() {
    println!("Hello, world!");
}

数式の埋め込み

\$と\$で数式を囲うことで、本文中に数式を埋め込むことができます。 $$と$$で数式を囲うことで、独立した段落に数式を埋め込むことができます。

ソースコード

\\(x\\)の不定積分:

$$ \int x dx = \frac{x^2}{2} + C $$

表示結果

$x$の不定積分:

$$ \int x dx = \frac{x^2}{2} + C $$

フローチャートの埋め込み

本文中にmermaid.jsで記述された図を埋め込むことができます。

ソースコード

```mermaid
flowchart LR
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]
```

表示結果

    flowchart LR
        A[Start] --> B{Is it?}
        B -->|Yes| C[OK]
        C --> D[Rethink]
        D --> B
        B ---->|No| E[End]

文書校正する

文書校正およびMarkdownファイルのスタイルチェックを実行するためには、リポジトリのルートディレクトリで以下のコマンドを実行してください。チェックが実行され、指摘内容が表示されます。指摘に従い、文章を修正しましょう。

make check -k

一部の指摘については、自動で修正可能です。以下コマンドを実行してください。

make fix -k

makeの-kオプションを指定することで、すべてのツールでチェックすることを強制できます。 -kオプションを指定しない場合、一部のツールでの指摘しか表示されないことがあります。

Visual Studio Code への統合

Visual Studio Code (VSCode) を使用している場合、文書校正およびMarkdownファイルのスタイルチェックがVSCode上で行われるよう設定できます。以下手順に従って設定してください。

VSCodeの拡張機能markdownlintをインストールする (インストール済みの場合、実施不要)
VSCodeの拡張機能vscode-textlintをインストールする (インストール済みの場合、実施不要)
Gitリポジトリのルートディレクトリで以下コマンドを実行し、必要なツール一式をホスト環境にインストールする

make install-lint-tools

ツール一式はGitリポジトリのルートディレクトリ配下にインストールされるため、一般ユーザーの権限でインストール可能です。

ツール一式のインストール後、Dockerコンテナのアップデート等によりツールが更新された場合、上記コマンドを再度実行してください。更新されたツールによりチェックが行われるようになります。

その他のエディタ・IDEへの統合

VSCode以外のエディタ・IDEについても、markdownlint-cliやtextlintに対応したものであれば同等の機能が使用できるはずです。

ウェブサイトとして公開する

Markdownファイルに対する変更をcommitしGitHubへpushします。文章校正やMarkdownスタイルチェックの指摘への対応漏れがないことを確実にするため、別ブランチを作成して変更内容をcommitするのが良いでしょう。 mainブランチに対するPull Requestを作成し、GitHub Actionsのチェックが通ったことを確認したらマージしましょう。

変更がmainブランチに取り込まれると、公開されているウェブサイトの内容が更新されます。公開されたウェブサイトには以下URLからアクセスできます。

https://<username>.github.io/<repository>

<username>はGitHubのアカウント名、<repository>はGitリポジトリ名です。

ウェブサイト公開後

ここまでの手順で、mdbook-ja-templateを使ってウェブサイトを作成し、執筆した文章をウェブサイトとして公開できました。

ウェブ上の文書は公開後も自由に更新できます。読者からのフィードバックや、新たに得た知識を活かして、文章をより良くしていきましょう。

mdbook-ja-templateで使用しているmdBook、textlint等のツールには様々な設定項目やプラグインが存在します。使いこなすことでウェブサイトを改善したり、作業フローを自分好みなものに変更したりできるでしょう。

次章では、これらのツールの設定方法など、mdbook-ja-templateの応用的な使い方を紹介します。

応用的な使い方

mdbook-ja-templateの応用的な使い方を紹介します。

mdBookのカスタマイズ

mdBookのカスタマイズ方法を紹介します。

設定ファイル

mdBookの設定ファイルbook.tomlの内容を変更することで、mdBookの動作をカスタマイズできます。設定項目については、mdBookのドキュメントを参照してください。

mdbook-ja-templateのbook.tomlの内容は以下のとおりです。

[book]
authors = ["gifnksm <makoto.nksm+github@gmail.com>"]
title = "mdbook-ja-templateユーザーズガイド"
language = "ja"
src = "src"
multilingual = false

[output.html]
mathjax-support = true
additional-js = ["js/mermaid.min.js", "js/mermaid-init.js"]
git-repository-url = "https://github.com/gifnksm/mdbook-ja-template"
edit-url-template = "https://github.com/gifnksm/mdbook-ja-template/edit/main/{path}"
site-url = "/mdbook-ja-template/"

[output.linkcheck]

[preprocessor]

[preprocessor.mermaid]
command = "mdbook-mermaid"

プラグイン

mdBookはmdbook-*という形式のコマンドをプラグインとして組み込み、出力内容の変更などを行うことができます。 mdBookで利用可能なプラグインの一覧はThird party pluginsを参照してください。

mdbook-ja-templateでは以下のプラグインが組み込まれています。

mdbook-mermaid: mdBookにmermaid.jsサポートを追加するプラグイン
mdbook-linkcheck: ドキュメント中に無効なリンクが含まれていないかチェックするプラグイン

プラグインの追加

新たにプラグインを追加したい場合は、docker/Dockerfileを編集して、コンテナ内にプラグインをインストールしてください。プラグインのインストール方法やbook.tomlの設定方法はプラグインのドキュメントを参照してください。多くのプラグインはcargo install でインストールできます。

以下に、mdbook-tocプラグインをインストールする場合の例を示します。

まず、docker/Dockerfileを以下のように編集してください。

FROM ghcr.io/gifnksm/mdbook-ja:latest

# ↓追加
RUN cargo install mdbook-toc --version 0.9.0 --root /usr/local/bin

次に、book.tomlに以下を追加してください。

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

編集後make buildなどを実行すると、プラグインが有効になった状態でウェブサイトが生成されます。

textlintのカスタマイズ

textlintのカスタマイズ方法を紹介します。

設定ファイル

textlintの設定ファイル.textlintrcの内容を変更することで、textlintの動作をカスタマイズできます。設定項目については、textlintのドキュメントを参照してください。

mdbook-ja-templateの.textlintrcの内容は以下のとおりです。

{
  "filters": {},
  "rules": {
    "@textlint-ja/no-insert-dropping-sa": true,
    "@textlint-ja/no-synonyms": true,
    "@textlint-rule/no-duplicate-abbr": true,
    "doubled-spaces": true,
    "footnote-order": true,
    "ja-hiragana-fukushi": true,
    "ja-hiragana-hojodoushi": true,
    "ja-hiragana-keishikimeishi": true,
    "ja-no-orthographic-variants": true,
    "no-empty-section": true,
    "no-mixed-zenkaku-and-hankaku-alphabet": {
      "prefer": "半角"
    },
    "period-in-list-item": true,
    "prefer-tari-tari": true,
    "preset-ja-spacing": true,
    "preset-ja-technical-writing": true
  }
}

プラグイン

textlintはルールを導入することでチェック内容をカスタマイズできます。 textlintで利用可能なルールの一覧はCollection of textlint ruleを参照してください。

プラグインの追加

新たにルールを追加したい場合は、docker/Dockerfileを編集して、コンテナ内にルールをインストールしてください。ルールのインストール方法や.textlintrcの設定方法はルールのドキュメントを参照してください。多くのルールはcd /npm && npm install textlint-rule-* でインストールできます。

以下に、textlint-rule-no-todoプラグインをインストールする場合の例を示します。

まず、docker/Dockerfileを以下のように編集してください。

FROM ghcr.io/gifnksm/mdbook-ja:latest

# ↓追加
RUN cd /npm && npm install textlint-rule-no-todo@2

次に、.textlintrcに以下を追加してください。

{
    ...,
    "rules": {
        "no-todo": true
    }
}

編集後make checkなどを実行すると、ルールが有効になった状態で文書校正が行われます。また、make install-lint-toolsを実行している場合、再度実行してください。

markdownlintのカスタマイズ

markdownlintのカスタマイズ方法を紹介します。

設定ファイル

markdownlintの設定ファイル.markdownlint.jsoncの内容を変更することで、markdownlintの動作をカスタマイズできます。設定項目については、markdownlint-cliのドキュメントを参照してください。また、markdownlintのルールについてはmarkdownlintのドキュメントを参照してください。

mdbook-ja-templateの.markdownlint.jsoncの内容は以下のとおりです。

{
    "default": true,
    // MD013/line-length - Line length
    "md013": false
}

Docker Composeの使い方

mdbook-ja-templateではコマンド実行のためにDocker Composeを使用しています。 mdbook-ja-templateのdocker-compose.ymlの内容は以下のとおりです。

version: '3.9'

x-service:
  &default-service
  build: docker
  image: mdbook
  init: true
  volumes: [".:/book:rw"]
  network_mode: "host"
  user: "${UID}:${GID}"

services:
  mdbook:
    <<: *default-service
    entrypoint: ["mdbook"]
    command: ["serve"]

  mdbook-mermaid:
    <<: *default-service
    entrypoint: ["mdbook-mermaid"]

  mdbook-linkcheck:
    <<: *default-service
    entrypoint: ["mdbook-linkcheck"]

  markdownlint:
    <<: *default-service
    entrypoint: ["markdownlint"]

  textlint:
    <<: *default-service
    entrypoint: ["textlint"]

  exec:
    <<: *default-service
    entrypoint: []

コンテナ内のコマンドを直接実行する

コンテナ内のコマンドを直接実行する場合は、Docker Composeを使用してください。

UID, GIDの設定

Docker Composeの起動時は現在操作しているユーザのユーザIDとグループIDを環境変数として与える必要があります。コンテナ内のプロセスが生成するファイルの所有者をrootではなく、現在のユーザにするためです。

コンテナ内でmdbook helpコマンドを実行する場合は、以下のようにDocker Composeを実行してください。 UID, GIDは環境変数ではなくシェルの変数であるため、Docker Composeプロセスへと通知するために環境変数として明に設定する必要があります。

env UID=${UID} GID=${GID} docker compose run --rm mdbook help

.envファイルを用意することで、コマンドラインでUID/GIDを設定することを省略できます。以下コマンドを実行することで.envファイルが生成されます。すでに.envファイルが存在する場合、内容は上書きされてしまうので注意してください。

make setup-docker-compose
# => .envが生成される
docker compose run --rm mdbook help
# => UID, GIDの設定は暗黙的に行われる

コマンドの実行

以下の形式でコマンドを実行できます。

docker compose run --rm <コマンド名> <引数>

コマンド名には以下を指定できます。

mdbook: mdbookコマンドを実行する
mdbook-mermaid: mdbook-mermaidコマンドを実行する
mdbook-linkcheck: mdbook-linkcheckコマンドを実行する
markdownlint: markdownlintコマンドを実行する
textlint: textlintコマンドを実行する
exec: 引数で指定されたコマンドを実行する

コンテナ内でbashの会話型セッションを開始する場合のコマンド例を以下に示します。

docker compose run --rm exec bash

リファレンス

makeターゲット一覧
導入済みのtextlintプラグイン一覧

makeターゲット一覧

mdbook-ja-templateのMakefileで用意されているターゲットの一覧です。

make <ターゲット>のようにターゲットを指定してコマンド実行することで、対応した処理が実行されます。

ターゲット	説明
`build`	HTMLファイルのビルド (デフォルトターゲット)
`check`	Markdownファイルのチェック (すべてのツール)
`check-markdown`	Markdownファイルのチェック (markdownlint)
`check-mdbook`	Markdownファイルのチェック (mdbook test)
`check-textlint`	Markdownファイルのチェック (textlint)
`clean`	ビルド成果物の削除
`fix`	Markdownファイルの自動修正 (すべてのツール)
`fix-markdown`	Markdownファイルの自動修正 (markdownlint)
`fix-textlint`	Markdownファイルの自動修正 (textlint)
`help`	ヘルプメッセージの表示
`install-lint-tools`	ホスト環境にチェックツールをインストールする
`pull`	最新版のDockerコンテナをダウンロードする
`serve` ¹	HTMLファイルをビルドし、`http://localhost:3000/`でホストする
`setup-docker-compose`	Docker Compose 用の`.env`ファイルを作成する
`watch` ¹	HTMLファイルのビルド & Markdownファイル更新時の自動再ビルド

serveおよびwatchではサーバプロセスが立ち上がります。Ctrl-C等でプロセスを終了させるまで端末の処理は戻りません。