index of top level

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 による実際の出力例を以下に示す。

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 記載例

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 記載例

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: または : を記載して表のキャプションを指定する。

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

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

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 形式に変換する