mdbookで内部リンクを貼る方法と注意点

mdbookで内部リンクを貼るときに、README.mdへのリンクは現時点では少し工夫が必要である旨の備忘録です。

はじめに
mdbookで内部リンクを貼る
おわりに
参考

はじめに

mdbookはRust製のmarkdownドキュメントビルダーです。

README.mdへの内部リンクを貼ろうとした際に少しハマったので、備忘録を残します。

mdbookで内部リンクを貼る

内部リンクを貼る方法

まず、普通に内部リンクを貼る方法です。

相対パスでmarkdownファイルへのリンクを
[<リンクテキスト>](<リンク先mdファイルへの相対パス>)
形式で貼るだけで問題ありません。

html変換時の整合性はmdbookが担保してくれます。

## Normal Links

- Link to Section 1 aaa.md: [section_1 aaa](./section_1/aaa.md)

README.mdへの内部リンクを貼る際の注意点

README.mdへのリンクを貼るときは現時点(2023/03)では注意が必要です。

単純にREADME.mdへの相対リンクを書いても上手く機能しません。

// 上手くいかない例

- Link to Section 1 README.md with [./section_1/README.md](./section_1/README.md)

この問題は、README.mdの代わりにindex.mdまたはindex.htmlと書くことで回避できます。

// 解決策

- Link to Section 1 README.md with [./section_1/index.md](./section_1/index.md)
- Link to Section 1 README.md with [./section_1/index.html](./section_1/index.html)

これは、mdbookがREADME.mdへの相対リンクを、html変換後のindex.htmlに正しく変換できていないことに起因しています。

これを解決するPull Requestはすでに作成されていますが、現時点ではまだmergeには至っていないため、上記のような回避策が必要です。

Fix relative links to README.md files by chrstnst · Pull Request #1921 · rust-lang/mdBook · GitHub

まとめ

成功する内部リンク/失敗する内部リンクを実装例としてまとめます。

# Internal link Examples

## Normal Links

- Link to Section 1 aaa.md with [./section_1/aaa.md](./section_1/aaa.md)
  - Succeeded

## README.md Links

- Link to Section 1 README.md with [./section_1/README.md](./section_1/README.md)
  - Failed (404)
- Link to Section 1 README.md with [./section_1/README.html](./section_1/README.html)
  - Failed (404)
- Link to Section 1 README.md with [./section_1/index.md](./section_1/index.md)
  - Succeeded
- Link to Section 1 README.md with [./section_1/index.html](./section_1/index.html)
  - Succeeded