目次用HTMLの編集方法
mnmpepフォルダと同階層にあるindex.htmlは、ドキュメント全体の目次ページとして機能します。
このファイルは Pandoc
のビルドとは独立しており、手動で編集してドキュメント構造を反映させる必要があります。
その為、こういった目次ページが必要ない場合、この手順は不要です。
以下では、編集すべきポイントを順番に説明します。
１．タイトル（ブラウザタブに表示される文字）
<title>mnmpep-readme</title>この部分を書き換えると、ブラウザのタブに表示されるタイトルが変わります。
例：
<title>プロジェクトドキュメント</title>
→ ブラウザのタブに「プロジェクトドキュメント」と表示されます。
２．目次左上のタイトルリンク
<a id="titlepage-link" href="./index.html">mnmpep-readme</a>ここは 目次の左上に表示されるタイトル兼リンクです。
通常は、目次用HTMLをそのまま指定すればよいでしょう。
- 表示したいタイトル文字
- クリックしたときに開くページ（通常は目次用HTML）
を指定します。
例
html <a id="titlepage-link" href="./index.html">目次</a>
３．初期表示ページの指定（HOME定数）
<script>
const HOME = "overview.html";目次ページを開いたときに、本文エリアに最初に表示するページを指定します。
表紙として相応しいページのファイル名を記述しましょう。
４．メニュー構造（detailsタグ）
<nav class="menu-frame">は、目次部分全体を囲む枠です。
<nav class="menu-frame"> </nav>タグ内に<details>タグを記述することで、下記画像のような開閉式のメニュー項目階層を作ることができます。
この画像例だと、下記のような記述をすることになります。
<nav class="menu-frame">
<a id="titlepage-link" href="./overview.html">mnmpep-readme</a>
<details>
<summary>01.Overview & Installation</summary>
<div><a href="./overview.html" target="page-frame">1.Overview</a></div>
<div><a href="./installation.html" target="page-frame">2.Installation</a></div>
</details>
<details>
<summary>02.Usage</summary>
<div><a href="./usage.html" target="page-frame">1.Useage</a></div>
</details>
</nav>detailsタグ内の詳細
目次の開閉部分の構造は、以下のような <details>
タグで作ります。
<details>
<summary>01.Overview & Installation</summary>
<div><a href="./overview.html" target="page-frame">1.Overview</a></div>
<div><a href="./installation.html" target="page-frame">2.Installation</a></div>
</details>編集ポイント -
<summary>: メニューの見出し（クリック・タップで開閉） -<div><a ...>: 実際のページへのリンク
つまり、「章」→「その章に属するページ」という構造になります。
<summary> </summary>タグ内に、見出し内容を記述してください。
<div><a href="ページのURL" target="page-frame">ページのタイトル</a></div>の
-
href=の部分に各ドキュメントの相対パス("で囲ってください！)を記述しましょう。
-
<a ...> </a>の内部にページタイトルを記述しましょう。
サブメニュー（入れ子の<details>）
階層をさらに深くしたい場合は、<details>
の中にもう一つ <details> を入れます。
<details>
<summary>02.Usage</summary>
<div><a href="./usage.html" target="page-frame">1.Usage</a></div>
<details>
<summary>Advanced</summary>
<div><a href="./advanced1.html" target="page-frame">1.Advanced Topic</a></div>
</details>
</details>上記の例だと、下記画像のような構成でメニューが表示されます。
- 「Usage」という章の中に
- 「Advanced」というサブ章を作り
- その中にページを並べる
というツリー構造のメニューが作れます。
また、入れ子にした<details>の中に、更に<details>を入れることで、より深い階層構造を表現することもできます。
ドキュメントの内容構造が直感的にわかるようなメニュー作りが実現できます。
目次用HTML編集の流れ
flowchart TD
A["1. タイトルを編集"] --> B["2. 左上タイトルリンクを編集"]
B --> C["3. 初期表示ページ(HOME)を設定"]
C --> D["4. メニュー項目(details)を追加"]
D --> E["5. 必要ならサブメニューを入れ子で追加"]