# index of top level

Abstract
概要

# 1 概要

本ドキュメントは、Markdown と Pandoc によるドキュメント発行のサンプル、運用方法およびノウハウをまとめたものである。

# 2 言語切替

日本語と英語を同一の Markdown に記載できる。

発行する際に、それぞれの言語別タグを切り替えて処理を行うことから、成果物は単一言語向けとすることができる。

## 2.1 記載方法

### 2.1.1 ニュートラル言語

特殊タグで囲わない限り、 Markdown はニュートラル言語として扱われ、日英双方の成果物に含まれる。

### 2.1.2 日本語・英語

以下のタグで囲うことにより、それぞれの言語別の成果物にのみ表示される。

    <!--ja:
    日本語 (編集プレビューで非表示状態)
    :ja-->

    <!--ja:-->
    日本語 (編集プレビューで表示状態)
    <!--:ja-->

    <!--en:
    English Hidden in Markdown
    :en-->

    <!--en:-->
    English Visible in Markdown
    <!--:en-->

### 2.1.3 編集時の表示

編集時の表示・非表示は、発行後の表示状態に影響しない。

## 2.2 Sample

English Hidden in Markdown

English Visible in Markdown

## 2.3 Visual Studio Code 拡張機能

以下の Visual Studio Code 拡張機能により、編集時の言語切替作業の効率化が可能。

- vscode-multilang-md

# 3 詳細情報

文章に詳細情報を記載する場合は以下のタグを利用する。

## 3.1 記載方法

    <!--details:
    詳細 (編集プレビューで非表示状態)
    :details-->

    <!--details:-->
    詳細 (編集プレビューで表示状態)
    <!--:details-->

### 3.1.1 編集時の表示

編集時の表示・非表示は、発行後の表示状態に影響しない。

## 3.2 記載例

## 3.3 Visual Studio Code 拡張機能

以下の Visual Studio Code 拡張機能により、編集時の詳細切替作業の効率化が可能。

- vscode-multilang-md

# 4 インデックス (目次) の自動生成

`\toc` コマンドを使用して、指定された階層以下の Markdown ファイルから自動的にインデックス (目次) を生成できる。

## 4.1 基本的な使用方法

    \toc

現在のディレクトリにある Markdown ファイルのインデックスを生成する。

## 4.2 パラメータ付きの使用方法

    \toc depth=1 exclude="temp.md" exclude="draft/*"

## 4.3 パラメータ詳細

### 4.3.1 階層数指定 (depth)

- `depth=0`: 現在のディレクトリのみ (デフォルト)
- `depth=1`: 現在のディレクトリ + 1階層下まで
- `depth=2`: 現在のディレクトリ + 2階層下まで
- `depth=-1`: 制限なし (全階層を掘り下げ)

### 4.3.2 除外パターン (exclude)

    \toc exclude="temp.md"                    # 単一ファイル除外
    \toc exclude="draft/*"                    # パターン除外
    \toc exclude="temp.md" exclude="draft/*"  # 複数除外

- `"README.md"`: 特定ファイル
- `"draft/*"`: ディレクトリ配下全て
- `"*.tmp"`: 拡張子による除外

## 4.4 注意事項

- index.md または index.markdown が存在する場合、フォルダ名はそのファイルへのリンクになる
- index ファイル内の最初の `# タイトル` がフォルダの表示名として使用される

## 4.5 実際の例

`\toc depth=-1` による実際の出力例を以下に示す。

- 📁 sample
  index of top level
  - 📁 docsfw
    pub_markdown
    - 📁 sample
      index of top level
      - 📁 subfolder
        サブフォルダの index
        - 📁 svg-test
          drawio.svg 変換テスト
      - 📁 空白を 含むサブフォルダ
        空白を含むサブフォルダ
      - 📁 日本語を含むサブフォルダ
        日本語を含むサブフォルダ
      - 📄 codeblock-caption.md
        コードブロックキャプションののサンプル
      - 📄 crossref.md
        相互参照サンプル
      - 📄 image-width.md
        image-width
      - 📄 mermaid-caption.md
        Mermaid キャプションのサンプル
      - 📄 plantuml.md
        plantuml
      - 📄 repeatedly-test.md
        繰り返しテスト
    - 📄 browser-reuse.md
      共有ブラウザインスタンスについて
    - 📄 chrome-wrapper.md
      chrome-wrapper について
    - 📄 collapsible-list.md
      展開可能リスト機能 (collapsible-list)
    - 📄 insert-toc.md
      Pandoc 目次挿入 Lua フィルタ (insert-toc.lua)
    - 📄 mermaid.md
      Pandoc Mermaid Lua フィルタ (mermaid.lua)
    - 📄 mpe-heading-numbering.md
      Markdown Preview Enhanced での見出し自動採番
    - 📄 pandoc-linebreak.md
      Pandoc の改行コード: Windows/Linux 差異の実装調査
    - 📄 pipeline.md
      パイプラインに関する関連知見
    - 📄 puppeteer-offline-chrome.md
      Puppeteer で利用する Chrome のオフラインインストール方法
    - 📄 rsvg-convert.md
      rsvg-convert の独自実装について
    - 📄 submodule-docs-merge-design.md
      サブモジュール mdRoot マージ機能
    - 📄 windows-dot.md
      Windows における PlantUML の `dot.exe` 自動展開 (同梱 Graphviz) 仕様
  - 📁 doxyfw
    - 📄 c-doc-report.md
      C 言語ドキュメンテーションツール包括調査
    - 📄 cheatsheet.md
      CheatSheet
    - 📄 choose-input.md
      Doxyfile で複数の個別ディレクトリを対象に指定する方法
    - 📄 commands.md
      コマンド (タグ) の解説 日本語版
    - 📄 copydoc.md
      Doxygen の [@copydoc] 活用ガイド
    - 📄 defines.md
      define 値の展開について
    - 📄 direction.md
      パラメータの direction の処理
    - 📄 doxybook2-decolorize-output-research.md
      Doxybook2 出力の調査結果
    - 📄 doxybook2-decolorize-output-spec.md
      doxybook2-decolorize-output.sh 仕様
    - 📄 doxybook2-member-groups.md
      doxybook2 のメンバーグループ非対応について
    - 📄 doxybook2-plantuml.md
      doxybook2 への PlantUML 対応
    - 📄 doxygen-colored-output-research.md
      Doxygen 着色出力の調査結果
    - 📄 doxygen-colorize-output-spec.md
      doxygen-colorize-output.sh 仕様
    - 📄 doxygen-images.md
      Doxygen における画像の仕様
    - 📄 extract-graphs.md
      Doxygen 関連図の Markdown 挿入
    - 📄 how-to-edit-template.md
      doxybook2 のテンプレート編集方法
    - 📄 localization-todo.md
      テンプレート 日本語ローカライズ TODO
    - 📄 makefile-usage.md
      makefile 使用方法
  - 📁 makefw
    - 📁 gcc-warning-guide
      gcc 警告オプション運用ガイド
      - 📄 excluded-warnings.md
        推奨セットに含めない警告オプションとその理由
    - 📄 make-variable-assignment.md
      makefile の変数代入 “= と :=” の違い
    - 📄 makelevel-usage.md
      MAKELEVEL 変数による再帰 make の階層判定
    - 📄 makeparts.md
      makepart.mk / makechild.mk / makelocal.mk について
    - 📄 msvc-runtime-linkage.md
      MSVC ランタイムライブラリのリンクモデル
    - 📄 os-subdirectory-filtering.md
      サブディレクトリの OS フィルタリング
    - 📄 template-auto-selection.md
      makefile テンプレート自動選択機構
    - 📄 windows-utf8-console.md
      Windows における UTF-8 対応: マニフェストとコンソール出力
  - 📁 subfolder
    サブフォルダの index
    - 📁 svg-test
      drawio.svg 変換テスト
  - 📁 testfw
    - 📁 gtest
      - 📄 manual-build.md
        GoogleTest 手動ビルド手順
      - 📄 version-update.md
        GoogleTest バージョン更新ガイド
    - 📄 about-shared-lib-static-linking.md
      共有ライブラリビルド時の静的ライブラリ組み込み機能
    - 📄 about-struct.md
      構造体の宣言について
    - 📄 about-test-phase.md
      テストコードの各フェーズについての解説
    - 📄 check-categorization.md
      確認の細分化
    - 📄 gtest-color-rules.md
      GoogleTest 実行結果の着色ルール
    - 📄 how-to-expect.md
      How to expect
    - 📄 how-to-extern.md
      C 言語における `extern` と実体の理解
    - 📄 how-to-mock.md
      How to mock
    - 📄 how-to-test.md
      How to test
    - 📄 mock-injection-technique.md
      標準ライブラリへのモック注入テクニック
    - 📄 opencppcoverage-sources.md
      OpenCppCoverage の source 指定における中間一致の仕様
    - 📄 process-control-api.md
      プロセス制御 API
    - 📄 trace-level-process-control.md
      プロセス制御関数への traceLevel サポート追加（設計検討資料）
    - 📄 windows-cov-tools.md
      VSBT でのカバレッジツール選択ガイド
  - 📁 空白を 含むサブフォルダ
    空白を含むサブフォルダ
  - 📁 日本語を含むサブフォルダ
    日本語を含むサブフォルダ
  - 📄 codeblock-caption.md
    コードブロックキャプションののサンプル
  - 📄 crossref.md
    相互参照サンプル
  - 📄 image-width.md
    image-width
  - 📄 mermaid-caption.md
    Mermaid キャプションのサンプル
  - 📄 plantuml.md
    plantuml
  - 📄 repeatedly-test.md
    繰り返しテスト

# 5 画像の挿入

画像を図として挿入する場合、`[` `]` による図のタイトルを Markdown に記載する。

> Pandoc にて、タイトルが定義されていない画像は図として扱われず、書式が設定されないため。

# 6 PlantUML

PlantUML は各プラグインとの親和性を考慮し、以下の通り Markdown に記載する。

## 6.1 言語名

plantuml とする。

> puml は使用しない。

## 6.2 Plantuml タグ

`@startuml` `@enduml` は必ず記載する。

> PlantUML プラグインにて、ドキュメント内の PlantUML を出力する際の識別に使いるため。

## 6.3 タイトル

`@startuml` に続いてファイル名を記載する。

> Visual Studio Code の PlantUML プラグインにて、エクスポートする際のファイル名に使いられる。

また、上記とは別に `caption` キーワードにてタイトルを記載する。

> PlantUML の図の見出しとして使いられる。
> Pandoc での発行時には図のキャプションとなる。

背景色は、pandoc 側で透明にしている。

> skinparam backgroundColor transparent を自動付与している。
> すでに skinparam backgroundColor が定義されている場合は、置換する。

## 6.4 記載例

図の見出し
マインドマップの見出し

## 6.5 Chrome 拡張機能

以下の Chrome 拡張機能により、GitBucket での PlantUML 図形のレンダリングが可能。

企業内のイントラネット環境等で利用する場合、PlantUML サーバの指定を必ず行うこと。

- Pegmatite-gitbucket

# 7 Mermaid

Mermaid 記法について、以下の通り Markdown に記載する。
Mermaid と PlantUML は実現できることが重複する。PlantUML を優先して採用すること。

## 7.1 タイトル

コードブロックのファイル名として記載する。

## 7.2 記載例

Mermaid のキャプション

# 8 draw.io

draw.io は各プラグインとの親和性を考慮し、以下の通り Markdown に記載する。

## 8.1 形式

Markdown から引用して用いるため、drawio.svg とする。

Markdown から引用して表示した場合には代表シートのみ表示されるため、1 つの drawio.svg ファイルには複数シートを定義しない。

## 8.2 Markdown への引用

原則、drawio.svg ファイルは、Markdown から参照する。

単一ファイルとしての drawio.svg ファイルは、docx フォーマットや html-self-contained フォーマットの出力結果には含まれない。

## 8.3 記載例

draw.io のテスト

## 8.4 ノウハウ

### 8.4.1 draw.io でテキストを含む図形が正しく変換できない場合の対処

docx 変換後に `Text is not SVG - cannot display` と表示されるケースがある。これは draw.io が .svg の高度な機能 (foreignObject) を利用しているためである。

Why text in exported SVG images may not display correctly

この問題を回避するため、テキスト記入時は以下とする。

- 「テキスト」の 「ワードラップ」 のチェックを外す。
- 「テキスト」の 「フォーマットされたテキスト」 のチェックを外す。

Draw.io Integration プラグインを使用している場合は、`hediet.vscode-drawio.simpleLabels` の設定を行うことでデフォルトの動作を変更する。

> この設定を行っても、.svg へのエクスポート時の挙動が変わるのみで .drawio.svg ファイルの挙動は変わらないため、上記テキストの属性設定を行う必要がある。

### 8.4.2 ダーク テーマの Visual Studio Code で画面が見づらい場合

Draw.io Integration のテーマを loght テーマ (例: kennedy - light) に変更する。

- VSCodeでDraw.ioを編集できるようにするまで
- VScodeの拡張機能「Draw.io Integration」で背景色を白色に変更する方法

Visual Studio Code ステータスエリア (右下) の `Theme:` 部分をクリックすることで、拡張機能の設定を経由せずにテーマの変更ができる。

# 9 OpenAPI

OpenAPI ファイルは、widdershins により Markdown に変換後、Pandoc に渡される。

## 9.1 記載例

OpenAPI ファイルへ

# 10 AsyncAPI

現段階で、AsyncAPI の発行は未サポート。

AsyncAPI 1.0 形式については、widdershins により変換できる可能性があるが未検証。

# 11 リンク

Markdown 内のリンクは、.html や .docx への変換時も維持される。

サブフォルダの index へ

# 12 コードスニペット

## 12.1 Bash

    echo "Hello"

## 12.2 CSharp

    Debug.WriteLine("Test");
    Debug.WriteLine("日本");

# 13 表

列幅の指定方法 により、ページ幅に収まらなかった場合の列幅を指定できる。

表に続いて、`Table:` または `:` を記載して表のキャプションを指定する。

表のキャプション (`Table: 表のキャプション`)
No. | 内容
--- | ---
1 | てすと
2 | テスト
3 | Test

表のキャプション (`: 表のキャプション`)
No. | 内容
--- | ---
1 | てすと
2 | テスト
3 | Test

セル内に改行を挿入する場合は、`<br />` を使用する。

セル内での改行を含む表
No. | ヘッダ1行目 ヘッダ2行目
--- | ---
1 | 内容1 内容2
2 | テスト
3 | Test

以下の形式 (Markdown pipe tables) も Pandoc ではサポートされる。
ただし、Markdown Preview Enhanced プラグインでのプレビューは現時点で非サポートのため、編集時の使い勝手を判断して使用すること。
Table: support grid tables

Markdown pipe tables による表 1
Distance (km) | Time (s)
--- | ---
12 | 34
56 | 78

Markdown pipe tables による表 2
L1 | L2 and L3
--- | ---
L2 | L3
AAA | BBB | CCC
DDDDD
EEEEE | FFF
GGG

# 14 メタデータ

Markdown の先頭に以下のように記載する。

    ---
    author:
        - author               <- 「作成者」プロパティ
        - author2              <- 複数人定義可能
    subject: "subject"         <- 「件名」プロパティ
    description: "description" <- 「コメント」プロパティ
    abstract-title: "Abstract" <- 「概要タイトル」プロパティ
    abstract: "概要"           <- 「概要」プロパティ
    ---

# 15 改ページ

docx 変換時に改ページを挿入したい場合は、`\newpage` を挿入する。

これは 1 つ目のパラグラフです。

これは 2 つ目のパラグラフです。

## 15.1 メタデータの扱い

- 第 1 レベルのタイトルが、文書のタイトルになる (title の指定は無視される)。
- 以下のルールで著者が設定される。
  1. メタデータの author が指定されている
     → メタデータの author
  2. pub_markdown.config に autoSetAuthor: true が指定されている場合
     1. git コマンドが使えない
        → 空文字
     2. Git 管理下にない
        → 空文字
     3. Git 管理下にあり、コミット履歴あり
        → コミッターリスト (新しい順、重複排除)
- 以下のルールで日付が設定される。
  1. メタデータの date が指定されている
     → メタデータの date
  2. pub_markdown.config に autoSetDate: true が指定されている場合
     1. git コマンドが使えない
        → ファイルの最終更新時刻 (RFC2822)
     2. Git 管理下にない
        → ファイルの最終更新時刻 (RFC2822)
     3. Git 管理下にあり、変更あり
        → ファイルの最終更新時刻 (RFC2822) + 最終コミットID + “+”
     4. Git 管理下にあり、変更なし
        → 最終コミット時刻 (RFC2822) + 最終コミットID

# 16 Pandoc テンプレート

bin/styles 以下にカスタマイズされた Pandoc テンプレートがある。

## 16.1 html

`pandoc -D 'html'` コマンドで出力されたデフォルトテンプレートに置き換えることで、デフォルトの出力に変更できる。

## 16.2 docx

`pandoc -o custom-reference.docx --print-default-data-file reference.docx` コマンドで出力したサンプルを Word テンプレート形式 (.dotx) で出力したものに置き換えることで、デフォルトの出力に変更できる。

図の幅はページサイズおよび余白に基づいて Pandoc で調整される。とじしろ (w:gutter) は考慮されないため、とじしろを定義した場合は図の横幅が期待通りとならない。テンプレート作成時は留意すること。
→ Pandoc 3.1.6 より、ページ設定の余白のとじしろが反映されていないバグが修正された。Gutters on margin specs not picked up from custom-reference.docx (HTML to .docx) #8946

# 17 発行方法

- Visual Studio Code で、タスク “exec pandoc” (Ctrl + Shift + B) を実行する。
- 現在開いている Markdown のみを対象に発行を行う場合は、タスク “exec pandoc (current file)” を実行する。

成果物は、/docs 配下に、言語別、フォーマット別に生成される。

# 18 参考にしたサイト

- Markdown を pandoc で HTML 化するときのノウハウ
- 44 種類のフォーマットに対応した Pandoc で Markdown を HTML 形式に変換する