GFM、CommonMark、Pandoc Markdownの構文比較

Markdown は、同じファイルが GitHub、Hugo、Obsidian、Pandoc などで異なる表示になるまで、一見一つの言語のように見えます。そして、問題は Markdown が信頼できないことではありません。

「Markdown」は、単一の普遍的な文書形式ではなく、関連する構文、パーサー、プラットフォーム機能のファミリーを指していることにあります。CommonMark は正確な移植可能なコアを定義し、GitHub Flavored Markdown（GFM）はソフトウェアのコラボレーションに有用な機能を追加し、Pandoc Markdown は言語を真剣な文書作成フォーマットに拡張します。

どれを選ぶかは、ドキュメントがどこでレンダリングされるべきかに依存します。README ファイル、Hugo ブログ記事、学術論文それぞれが異なる要件を持っています。この比較は、より広いドキュメンテーションツール の一部であり、正式な派手、プラットフォーム固有の拡張機能、実用的な移植性ルールをカバーし、対象環境に最適な構文を選べるようにします。素早い構文リファレンスとして、Markdown チートシートでは、基本的な整形要素を扱っています。

Markdown は一つの言語ではない

元の Markdown 構文は、意図的に小さく、緩く指定されていました。これは読みやすく実装しやすくしましたが、異なるパーサーが曖昧な入力を異なる方法で解釈し始めました。

CommonMark は、基本的な Markdown 構造の一貫したパーシングルールを定義するために作成されました。GitHub Flavored Markdown（通常 GFM と呼ばれます）はその基盤の上に、広く使用されるいくつかの拡張機能を追加しています。

Pandoc Markdown は異なるアプローチを取ります。小さなウェブ向けの構文にとどまるのではなく、引用、メタデータ、脚注、定義リスト、属性、数式表記といった文書機能を追加します。

単純化された関係は次のようになります。

この階層は有用ですが、すべての実装で正確な継承関係ではありません。各レンダラーは構文を独立して有効化、無効化、追加できます。

簡単な答え

移植性が最も重要な場合、CommonMark 互換の構文を使用してください。

README ファイル、プルリクエスト、問題テンプレート、主に GitHub 互換プラットフォーム向けに意図された技術ドキュメントを作成する場合は GFM を使用してください。

ソースドキュメントが PDF、DOCX、EPUB、LaTeX、スライド、または引用とメタデータ付きの学術論文に変換されなければならない場合は、Pandoc Markdown を使用してください。

Hugo 技術ブログには、CommonMark コアと、サイトが明示的に有効化している Goldmark 拡張機能を使用してください。Hugo が GFM 互換と説明されているという理由だけで、GitHub で見られるすべての機能が動作すると仮定しないでください。

意見のある視点: Hugo 技術ブログのために一つのルールだけ覚えるなら、CommonMark と GFM スタイルのテーブルおよびタスクリストをデフォルトと扱い、他のすべて — 脚注、数式、呼び出し、ヘッダー属性 — を仮定のデフォルトではなく、明示的かつテストされた拡張機能として扱うべきです。この単一の習慣により、以下に説明されている移植性の失敗の大部分を防げます。

CommonMark: 移植可能なコア

CommonMark は、基本的な Markdown 言語の正式な仕様です。その主な貢献は、大規模な機能集合ではなく、一貫したパーシングです。

パーサーがどのように解釈すべきかを定義します：

• パラグラフ
• ATX ヘッダーと Setext ヘッダー
• 引用ブロック
• 番号付きリストと番号なしリスト
• フェンストコードブロックとインデントコードブロック
• 強調（イタリック）と強い強調（ボールド）
• リンクと画像
• リファレンススタイルのリンク
• インラインコード
• テーマティックブレイク
• 生の HTML ブロック
• ハードブレークとソフトブレーク

CommonMark ドキュメントは、プレゼンテーション層で異なる挙動を示す可能性があります。CSS、構文ハイライト、ヘッダーアンカー、HTML 消毒、リンクポリシーは、コアのパーシングルールの外にあります。

したがって、CommonMark は信頼できる構造ベースラインとして扱うべきであり、すべてのレンダラーが同じページを生成するという約束ではありません。

移植可能な CommonMark の例

# Service Deployment

The service exposes a small HTTP API.

## Requirements

- Linux
- Docker
- 8 GB of memory

## Start the service

```bash
docker compose up -d
```

See the [configuration guide](configuration.md) for details.

このタイプのドキュメントは、ほぼすべての最新の Markdown 環境で動作します。派手固有の拡張機能に頼らずに、ヘッダー、パラグラフ、リスト、フェンストコード、通常のリンクを使用しています。

GitHub Flavored Markdown: ソフトウェアプロジェクトのための CommonMark

GitHub Flavored Markdown は、CommonMark をベースにした正式な派手です。CommonMark のパーシングモデルを保持し、リポジトリのドキュメンテーションとコラボレーションで一般的に必要な機能を追加します。

正式な GFM 仕様は、以下を追加します：

• パイプテーブル
• タスクリスト項目
• 取り消し線
• 拡張オートリンク
• 一部の生 HTML タグまわりの制限

これらの拡張機能は非常に一般的であり、多くのユーザーが標準 Markdown の一部だと思っており、それは CommonMark コアの一部ではありません。

GFM テーブル

| Backend | Best use |
|---|---|
| Ollama | Local experiments |
| vLLM | Shared inference |
| SGLang | Structured workloads |

厳密な CommonMark パーサーは、これを通常のテキストとして扱うことが許可されています。GFM 互換のパーサーはこれをテーブルとして認識します。テーブル構文と整列オプションについてのより深い見解は、Markdown におけるテーブルをご覧ください。

GFM タスクリスト

- [x] Install Docker
- [x] Download the model
- [ ] Add monitoring

タスクリスト構文は、問題、プルリクエスト、プロジェクトドキュメントに有用です。サポートするレンダラーの外では、リテラルの角括弧を含む通常のリストとして表示される可能性があります。

GFM 取り消し線

Use the ~~old endpoint~~ new endpoint.

取り消し線は広くサポートされていますが、依然として移植可能な CommonMark 構文ではなく拡張機能です。

GFM オートリンク

GFM は、角括弧や明示的なリンク構文を必要とせずに、より多くの URL 類似およびメール類似のテキストを認識します。

Visit https://example.com/docs for details.

厳密な CommonMark では、明示的なオートリンクは角括弧を使用します：

<https://example.com/docs>

ドキュメントが不明な Markdown プロセッサを通って移動しなければならない場合、明示的な形式の方が安全です。

GitHub.com は正式な GFM よりも多くのことをサポートする

混同の一般的な原因は、GitHub で見えるすべての Markdown 機能が GFM 仕様に属すると仮定することです。

そうではありません。

GitHub.com は、GFM パーサーの周囲にプラットフォームレベルの処理と機能を追加します。コンテキストに応じて、GitHub はサポートできます：

• 数式表現
• Mermaid 図
• アラート
• 問題およびプルリクエストへの参照
• ユーザーおよびチームのメンション
• コミット参照
• イモジショートコード
• 折りたたみ可能な HTML セクション
• カラープレビュー
• リポジトリ相対リンク
• 自動ヘッダーアンカー

これらの機能の一部は構文の拡張です。他の一部は後処理の動作や、GitHub データとの統合です。

この区別は重要であり、別のレンダラーが、GitHub の数式レンダラー、Mermaid 統合、問題参照、アラースタイルを実装せずに GFM 互換を正確に主張できる可能性があるためです。

GitHub Mermaid 図

GitHub は、mermaid とマークされたフェンストコードブロックを図としてレンダリングします：

```mermaid
flowchart LR
    A[Markdown] --> B[Rendered diagram]
```

汎用の GFM レンダラーは、同じブロックをハイライトされたソースコードとして表示する可能性があります。Markdown は依然として有効ですが、強化されたレンダリングはプラットフォーム固有です。Mermaid 構文の実践的な入門については、Mermaid 図 クイックスタートをご覧ください。

GitHub 数式表現

GitHub は、ドル記号区切りと追加のエスケープ形式を使用して、インラインおよびブロックの数式表現をサポートします。

The cache size is approximately $2nlhd$ bytes.

$$
C = 2nlhd
$$

数式は正式な GFM の一部ではありません。このコンテンツを別のレンダラーに移動するには、KaTeX、MathJax、または Pandoc 数式サポートのような互換の数式拡張機能が必要です。

GitHub アラート

GitHub は、次のようなアラートスタイルの引用ブロックをサポートします：

> [!WARNING]
> Changing this setting clears the cache.

GitHub では、これはスタイル付きの警告として表示される可能性があります。プレーンな CommonMark レンダラーでは、通常、[!WARNING] を含む通常の引用ブロックとして表示されます。

このフォールバックは読みやすく、これにより GitHub アラートは完全に消えてしまう拡張機能よりも危険性が低くなります。それでもなお、移植可能なプレゼンテーション要素ではありません。

Pandoc Markdown: 文書言語としての Markdown

Pandoc Markdown は、特定のウェブサイトではなく、文書変換のために設計されています。HTML、PDF、DOCX、EPUB、LaTeX、プレゼンテーション、その他の形式を生成するためのソース構文として Markdown を使用します。

デフォルトの Markdown リーダーには、大規模な拡張機能セットが含まれています。重要な機能には以下があります：

• YAML メタデータブロック
• 脚注
• 引用
• 複数のテーブル形式
• 定義リスト
• 数式表記
• ヘッダー識別子と属性
• コードブロック属性
• フェンストディビジョン
• ブラケット付きスパン
• 上付き文字と下付き文字
• ストライクアウト
• ラインブロック
• 番号付き例リスト
• 生の LaTeX
• 生の HTML
• 自動セクション番号付け
• 参考文献処理

Pandoc Markdown は、CommonMark や正式な GFM よりもはるかに表現力豊かです。その表現力はパブリッシングに強力ですが、交換形式としては安全ではありません。

Pandoc 脚注

Markdown has several incompatible dialects.[^dialects]

[^dialects]: CommonMark, GFM, and Pandoc Markdown are three
    important examples.

脚注構文は多くの現代的なツールでサポートされていますが、CommonMark や正式な GFM の一部ではありません。

GitHub は現在、いくつかのコンテンツコンテキストで脚注をレンダリングしますが、それは GitHub プラットフォーム機能であり、正式な GFM の保証ではありません。CommonMark または GFM 互換のみを主張するレンダラーはそれらをサポートしない可能性があります。

Pandoc 引用

PagedAttention improves KV cache memory management
[@kwon2023pagedattention].

参考文献ファイルと引用スタイルを使用すると、Pandoc はこれをフォーマットされた学術引用と参考文献に変換できます。

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

引用構文はサポートされていないレンダラーでも読みやすく残りますが、Pandoc または他の互換の引用プロセッサなしでは、フォーマットされた参照にはなりません。Pandoc のリーダー側の柔軟性は、逆方向の変換ワークフローの基盤でもあります — Pandoc の拡張派手を中間形式として使用する実用的な例については、Word ドキュメントを Markdown へ変換するをご覧ください。

Pandoc 定義リスト

CommonMark
: A precise specification for core Markdown.

GFM
: A CommonMark-based dialect with software-oriented extensions.

Pandoc Markdown
: An extended authoring format for document conversion.

定義リストは、マニュアル、用語集、技術書籍に有用です。それらをサポートしないレンダラーでは、コロン行がプレーンテキストとして表示され続けるため、通常はうまく劣化しません。

Pandoc ヘッダー属性

## Cache Configuration {#cache-config .deployment}

Pandoc は、波括弧を明示的な識別子とクラスリストとして解釈します。他の多くの Markdown レンダラーは、属性テキストをヘッダー内で直接表示します。

これは、どこでもレンダリングされることを期待される文書に配置すべきでない有用な構文の明確な例の一つです。

Pandoc フェンストディビジョン

::: warning
Changing this option restarts the server.

Pandoc は、これをクラス付きの構造ディビジョンに変換します。テンプレート、CSS、フィルタ、または出力ライターが、その構造がどのように見えるべきかを決められます。

ほとんどの CommonMark と GFM レンダラーはフェンスを認識しません。それらはコロンとコンテンツを通常のテキストとして表示します。

CommonMark vs GFM vs Pandoc Markdown

以下のマトリクスは、GitHub.com、Hugo、Obsidian、GitLab、または他のプラットフォームが追加するすべての機能ではなく、正式な派手について説明しています。

「いいえ」は、プラットフォームがその機能をサポートできないという意味ではありません。その機能は、その派手の正式な仕様によって保証されないという意味です。

GitHub でどの構文が動作しますか？

README ファイル、問題、プルリクエスト、ディスカッション、ウィキでは、GFM が自然なベースラインです。

一般的に使用できます：

• CommonMark 構文
• テーブル
• タスクリスト
• 取り消し線
• 拡張オートリンク
• 構文ハイライト付きコードフェンス
• GitHub 固有の参照
• GitHub がサポートする数式
• GitHub がサポートする図
• GitHub アラート
• コンテンツサーフェスがサポートする場所での脚注

移植性のリスクは、GitHub が正式な GFM 以外の追加レンダリングを行う場合に始まります。Mermaid 図、数式表記、問題参照、アラートのプレゼンテーションは、GitHub 外では生存するかもしれません。

他の場所でも公開されるリポジトリファイルでは、GitHub のプレビューを権威とせず、第二のレンダラーでソースをテストしてください。

Hugo でどの構文が動作しますか？

Hugo はデフォルトの Markdown レンダラーとして Goldmark を使用します。Goldmark は CommonMark に準拠し、GFM の重要な部分と互換性のある拡張機能を提供します。

典型的な Hugo 設定では、以下がよく機能します：

• CommonMark 構造
• フェンストコードブロック
• パイプテーブル
• 取り消し線
• タスクリスト
• 自動ヘッダー ID
• 構文ハイライト
• 拡張機能が有効化されている場合の脚注
• 有効化されている場合の定義リスト
• 有効化されている場合のタイポグラフィック置換

Hugo は、Markdown 以外の手段を通じて機能を追加します：

• フロントマター
• ショートコード
• レンダリングフック
• ページリソース
• 内部参照関数
• テンプレート処理
• サイト設定

これらの Hugo 機能は、Markdown ファイルとともに移動しません。Hugo のデプロイの実践的な例については、Hugo を AWS S3 にデプロイするをご覧ください。

Hugo フロントマターは Markdown コンテンツではない

Hugo ページは通常、YAML、TOML、または JSON メタデータから始まります：

---
title: "Markdown Compatibility"
description: "Compare Markdown dialects and renderers."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc も YAML メタデータブロックを認識できますが、独自のテンプレートとライターに従ってフィールドを解釈します。GitHub は通常、ブロックを YAML 似たセクションとして表示するか、特定のシステムでのみリポジトリメタデータとして扱います。

したがって、同じ構文は、同じセマンティクスを持たずとも、複数のツールで認識される可能性があります。

Hugo における生 HTML

標準的な Hugo 設定では、Goldmark はデフォルトで潜在的に不安全な生 HTML をレンダリングしません。

次のようなブロック：

<div class="notice">
  Restart the service after changing this value.
</div>

は、生 HTML レンダリングが有効化されていないか、コンテンツがショートコードまたはレンダリングフックを通じて実装されていない限り、省略される可能性があります。

管理された技術ブログでは、生 HTML を有効にすることは合理的です。それでもなお、ソースの移植性が低下するため、意識的なサイトレベルの決定であるべきです。

Hugo における Mermaid

フェンストされた mermaid ブロックは、Hugo テーマ、レンダリングフック、ショートコード、または JavaScript パイプラインがそれを図に変換しない限り、まだ単なるコードブロックです。

したがって、GitHub と Hugo は、完全に異なるレンダリングメカニズムを使用して、同じ Mermaid ソースを受け入れる可能性があります。

Pandoc でどの構文が動作しますか？

Pandoc は明示的に複数の Markdown 派手を読み取ることができます：

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

これは、Pandoc の最も有用な移植性功能の一つです。オペレーターは、あいまいな .md ファイル拡張子に頼るのではなく、ソースが使用すると主張している派手を Pandoc に伝えることができます。

Pandoc は、個々の拡張機能を有効化または無効化させることもできます：

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

または、より狭い形式から開始して、1 つの機能を追加することもできます：

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

利用可能な拡張機能を次のように確認できます：

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

この拡張機能モデルは強力ですが、「Pandoc Markdown」が常に1 つの固定設定であるわけではありません。ビルドコマンドとデフォルトファイルは、文書仕様の一部です。

Obsidian でどの構文が動作しますか？

Obsidian はノートを Markdown ファイルとして保存しますが、その作成モデルにはいくつかのアプリケーション固有の機能が含まれています。

一般的な例には以下があります：

• ウィキリンク
• 埋め込みノート
• 埋め込みファイル
• 呼び出し
• ブロック参照
• タグ
• プロパティ
• ハイライト
• コメント
• プラグインからの Dataview クエリ
• アプリケーション固有の URI リンク

次のようなウィキリンク：

[[Markdown Compatibility]]

は、Obsidian ボールト内で意味があります。GitHub、CommonMark、およびデフォルトの Pandoc リーダーは、通常、リテラルのブラケット付きテキストとして表示します。

埋め込みは、さらにアプリケーション固有です：

![[compatibility-table]]

参照されるコンテンツは、ファイル自体には存在しません。したがって、ノートをエクスポートまたは公開するには、埋め込みを解決する展開ステップが必要です。

Obsidian は、.md ファイルへの保存が Markdown の移植性を保証しないことの良い例です。ナレッジマネジメントツールとしての Obsidian の実践的な見解については、パーソナルナレッジマネジメントのための Obsidianをご覧ください。

GitLab でどの構文が動作しますか？

GitLab Flavored Markdown は、コアとして CommonMark を使用し、テーブルやタスクリストのような GFM 機能を含みます。その後、クロスリファレンス、数式表記、図、および他のコラボレーション機能を含む GitLab 固有の動作を追加します。

保守的な GFM で書かれた README は、通常、大きな損傷なく GitHub と GitLab の間で移動できます。

プラットフォーム統合は、信頼できるほどには移動しません。問題参照、ユーザーメンション、図、数式の処理、特殊なブロック構文は、基本的な Markdown が読みやすく残っていても、異なる動作をする可能性があります。

プラットフォームサポートマトリクス

このマトリクスは、一般的なデフォルトの動作を説明します。テーマ、プラグイン、拡張機能、および設定は、個別のセルを変更できます。

「はい」は、同じ HTML または視覚的なプレゼンテーションを保証するものではありません。環境が一般的な機能を認識するという意味です。

通常どこでも安全な構文

最も安全な移植可能なサブセットには以下が含まれます：

• # を使用した ATX ヘッダー
• 通常の段落
• ブロック間の空白行
• - を使用した番号なしリスト
• 1. を使用した番号付きリスト
• バッククォートを使用したフェンストコードブロック
• バッククォートを使用したインラインコード
• *text* を使用した強調
• **text** を使用した強い強調
• 通常のリンク
• 通常の画像
• 引用ブロック
• テーマティックブレイク
• 明示的な角括弧オートリンク

意図的に保守的なドキュメントは、次のようになるかもしれません：

# Deployment Guide

This guide explains how to deploy the service.

## Requirements

- Docker
- Linux
- A supported GPU

## Configuration

Create a file named `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

For more information, see the [configuration reference](config.md).

> Back up existing data before upgrading.

この構文は、テーブル、脚注、属性、呼び出し、またはプラットフォーム処理に依存しないため、よく移植されます。

一般的に壊れる構文

移植性の問題は、少数の機能の周りに集まる傾向があります。

パイプテーブル

パイプテーブルは、GFM 向けのツールでよくサポートされていますが、厳密な CommonMark ではサポートされていません。

テーブルは、それを認識しないパーサーを通すと、読めないテキストに劣化する可能性があります。非常に移植可能なドキュメントのために、短いリストまたはビルドステップ中に生成されるセマンティック HTML を考慮してください。

脚注

脚注構文は一般的になりましたが、依然として拡張機能です。

異なるツールは、次のように異なる可能性があります：

• 一つの脚注形式のみをサポートする
• 脚注を異なる場所に配置する
• 異なる識別子を生成する
• 複数段落の脚注を拒否する
• ソースをリテラルにレンダリングする

公開パイプラインが既知の場合に脚注を使用してください。任意のシステムでレンダリングされなければならない README ファイルでは、それらに依存しないでください。

ヘッダー ID と属性

この Pandoc 構文は移植可能ではありません：

## Installation {#installation .procedure}

移植性が重要な場合、通常のヘッダーを使用し、レンダラーが独自のアンカーを生成するさせます。

また、すべてのターゲットが同じスラギフィケーションルールを使用しない限り、自動生成されたヘッダー ID へのリンクをハードコードしないでください。

呼び出しとアラート

GitHub、Obsidian、GitLab、MkDocs、Docusaurus、および Hugo テーマはすべて、呼び出しのようなブロックをサポートできますが、異なる構文を使用していることが多いです。

移植可能なフォールバックは、通常の引用ブロックです：

> Warning: Back up the database before upgrading.

視覚的には目立たなくなりますが、意味はどこでも保持されます。

ウィキリンク

ウィキリンクは、ナレッジマネジメントツール内で簡潔です：

[[KV Cache]]

ターゲットパス、ファイル名、ヘッダールール、および解決動作がアプリケーションに属するため、交換構文としては不適切です。

公開を意図したコンテンツでは、標準の Markdown リンクを使用してください：

[KV cache](kv-cache.md)

生 HTML

生 HTML は、Markdown がレイアウトを表現できない場合の通常の逃げ場です。また、移植性とセキュリティの一般的な失敗でもあります。

レンダラーは、次のように動作する可能性があります：

• HTML を削除する
• エスケープする
• 選択された要素を消毒する
• ブロックは許可するがインライン要素は許可しない
• HTML 内の Markdown パースを拒否する
• 信頼されたモードでのみ変更なしで渡す

公開ターゲットが管理されている場合のみ、生 HTML を使用してください。

数式表記

ドル記号区切りの数式は人気がありますが、普遍的に解釈されるわけではありません。

ソース：

The complexity is $O(n^2)$.

は、次のようになる可能性があります：

• レンダリングされた数式
• ドル記号付きの通常のテキスト
• 誤った強調
• 異なる数式パーサーへの入力

1 つの数式パイプラインを選び、すべてのターゲット環境でテストしてください。

Mermaid と他の図ブロック

Mermaid コードフェンスは構文的に安全であり、サポートされていないレンダラーは通常それをコードとして表示します。

意味的な結果は依然として異なります。読者は、GitHub でレンダリングされたアーキテクチャ図を見、別の環境では生の Mermaid ソースを見る可能性があります。

これは優雅な劣化であり、真の互換性ではありません。

Markdown 互換性の 3 つの層

互換性を 3 つの層に分離すると役に立ちます。

層 1: パーシング互換性

パーサーは構造を認識しますか？

例：ヘッダー、テーブル、脚注、フェンストディビジョン。

層 2: 変換互換性

プラットフォームは追加の処理を適用しますか？

例：

• Mermaid のレンダリング
• 引用の解決
• ウィキリンクの展開
• 問題番号のリンク
• ショートコードの処理
• 目次（TOC）の生成

層 3: プレゼンテーション互換性

結果は適切に美しく動作しますか？

例：

• テーブルのスタイル
• 構文ハイライト
• アラートの色
• ヘッダーアンカー
• レスポンシブ画像
• 脚注の配置
• 数式フォント

2 つのプラットフォームは、同じ構文をパースしながら、大幅に異なるプレゼンテーションを生成できます。

より良い移植性モデル

ファイルが「有効な Markdown」かどうかを尋ねるのではなく、より狭い 4 つの質問をしてください：

1. ソースはどの派手で書かれていますか？
2. どのパーサーがそれを読み取りますか？
3. どの拡張機能が有効化されていますか？
4. その後、どのプラットフォーム変換が実行されますか？

例えば：

Dialect: CommonMark plus GFM tables
Parser: Goldmark
Extensions: tables, strikethrough, task lists, footnotes
Platform: Hugo
Additional processing: render hooks and Mermaid JavaScript

この説明は、「サイトは Markdown を使用しています」と言うよりもはるかに有用です。

使用ケースに基づく派手の選択

README ファイル

GFM を使用してください。

README ファイルは、以下から利益を得ます：

• テーブル
• タスクリスト
• フェンストコード
• オートリンク
• 取り消し線
• GitHub 参照

リポジトリが GitLab にミラーリングされ、パッケージレジストリでレンダリングされ、または生成されたドキュメントに 포함される場合、GitHub 固有の機能への過度な依存を避けてください。

Hugo 技術記事

文書化された Goldmark 拡張機能セットと CommonMark 互換の Markdown を使用してください。

テーブル、コードフェンス、脚注、Mermaid は、ビルドパイプラインを管理しているため合理的です。大量の生 HTML の埋め込みよりも、Hugo ショートコードやレンダリングフックを優先してください。

Hugo 固有の構文を分離し、見つけやすく保ってください。

学術文書

Pandoc Markdown を使用してください。

引用、参考文献処理、脚注、メタデータ、数式表記、クロスリファレンス、および PDF または DOCX への変換は、移植性の低下を正当化します。

Pandoc コマンド、デフォルトファイル、フィルタ、参考文献、テンプレートをソースの隣に保存してください。ソースファイルだけでは、ビルドを完全に記述しません。

書籍と長文ドキュメンテーション

複数の出力形式が重要な場合、Pandoc Markdown は通常、3 つの選択肢の中で最も強いです。

文書の複雑さが大きくなるにつれて、定義リスト、引用、属性、メタデータ、構造化変換がより重要になります。

Git リポジトリにホストされるウェブ限定のドキュメンテーションの場合、GFM または CommonMark ベースのドキュメンテーションジェネレーターの方が単純なままである可能性があります。

ノートとパーソナルナレッジベース

アプリケーション機能が本当の価値を提供する場合、選択されたノートアプリケーションのネイティブ構文を使用してください。

Obsidian ウィキリンク、埋め込み、呼び出しはボールト内で有用です。エクスポートをコンパイルプロセスとして扱い、生のファイルがすでに移植可能な出版物であるとは仮定しないでください。

不明なシステム間の共有ドキュメンテーション

保守的な CommonMark サブセットを使用してください。

避けてください：

• ウィキリンク
• プラットフォームアラート
• ヘッダー属性
• 引用
• 生 HTML
• カスタムコンテナ
• アプリケーション埋め込み
• ショートコード

移植性は通常、利便性機能の手放しを必要とします。

移植可能な Markdown のための実践的なルール

CommonMark 構造から始める

ドキュメントの骨格に CommonMark を使用してください：

• ヘッダー
• パラグラフ
• リスト
• リンク
• 画像
• 引用ブロック
• コードブロック

これにより、オプションの拡張機能が失敗しても、主な意味が生存することが保証されます。

GFM 機能を意識的に追加する

すべての重要なターゲットがサポートしている場合、テーブルとタスクリストは合理的です。

「ほとんどのツールが GFM をサポートする」と仮定せず、正確なターゲットをテストしないでください。GFM 互換を主張しながら、選択された拡張機能のみを有効にしているものもあります。

プラットフォーム拡張機能を分離する

プラットフォーム固有の構文を、明確に識別できるブロックに保ってください。

例えば、Hugo ショートコード、Pandoc 引用、または Obsidian 埋め込みを、すべての段落に散らばらせるのではなく、中心化してください。

分離は、後の変換を容易にします。

優雅な劣化を優先する

Mermaid ブロックは、読めるソースコードに劣化します。GitHub アラートは、引用ブロックに劣化します。

ウィキ埋め込みは、説明のないファイル名に劣化するかもしれませんが、Pandoc フェンストディビジョンは、コンテンツの周囲に句読点を露出する可能性があります。

フォールバックが理解可能に残る拡張機能を選びます。

自動生成されたヘッダー ID に依存しない

ヘッダーアンカーアルゴリズムは、GitHub、Hugo、Pandoc、ドキュメンテーションジェネレーターの間で異なります。

ドキュメント間のリンクには、ターゲットパイプラインが管理されている場合のみ、レンダラーがサポートする明示的な ID を使用してください。それ以外の場合は、生成されたフラグメントではなく、ドキュメントにリンクしてください。

ビルド設定をコンテンツとともに保つ

Pandoc 拡張機能、Hugo 設定、プラグイン、フィルタ、JavaScript 統合は、Markdown の動作を決定します。

関連する設定ファイルをソースとともにコミットしてください：

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

.md 拡張子だけでは、公開環境を捉えません。これらの決定を文書化する構造化されたアプローチについては、AI 主導開発のための意思決定記録をご覧ください。

すべての重要なターゲットに対して Markdown をテストする

1 つのエディタでのビジュアルプレビューでは十分ではありません。エディタは、本番レンダラーよりもリッチな派手をサポートしている可能性があります。

Pandoc の場合、明示的な入力形式をテストしてください：

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

警告と表示されるソースの句読点は、どの機能が派手固有であるかを明らかにします。

Hugo の場合、本番サイトをビルドしてください：

hugo --gc --minify

その後、エディタのプレビューだけに頼らず、生成された HTML を検査してください。

リポジトリの場合、実際のカスタリングプラットフォームでコミットされたファイルを表示してください。VS Code でのローカル Markdown 拡張機能は、GitHub や GitLab と一致しない可能性があります。

一般的なレンダリングの不一致のトラブルシューティング

1 つのプラットフォームで動作していたファイルが別のプラットフォームで壊れる場合、失敗は通常、繰り返し可能なパターンの中の 1 つに分類されます。以下のテーブルは、実際にどのように見えるかという症状、最も可能性の高い原因、およびそれを確認・修正するための具体的なコマンドまたはチェックをリストしています。

これらは、Markdown の「バグ」を仮定する前の最速の第一歩です — これらの不一致の大部分は、壊れた構文ではなく、欠落している拡張機能またはプラットフォーム固有の機能です。構文ハイライトの欠如やサポートされていない言語識別子などのコードフェンス固有の問題については、Markdown コードブロックの専用ガイドをご覧ください。

移植可能なサブセットをリンティングする

Markdown リンターはレンダラー互換性を保証できませんが、避けることのできる曖昧さを除去できます。

有用なルールには以下があります：

• 一貫したヘッダースタイルを使用する
• リストとコードブロックの周りに空白行を追加する
• インデントコードではなくフェンストを使用する
• コードフェンスの言語を指定する
• ヘッダーレベルのスキップを避ける
• 一貫したリストマーカーを使用する
• 句読点周囲の曖昧な強調を避ける
• 改行コードを一貫させる
• リンクと画像を検証する

マルチターゲット公開のために、構文リンティングだけに頼らず、各重要なレンダラーに対してビルドテストを追加してください。

Pandoc を使用した派手間の変換

Pandoc は、1 つの派手から別の派手への文書を正規化できます：

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

または、GFM を Pandoc Markdown へ変換します：

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

これは有用ですが、変換がすべての機能を保持することを保証するものではありません。

潜在的な損失には以下が含まれます：

• プラットフォーム固有の参照
• 呼び出しスタイル
• 複雑なテーブル
• 埋め込みアプリケーションオブジェクト
• カスタム属性
• 生 HTML の動作
• プラグイン構文
• 図のレンダリング
• 正確なスペースとフォーマット

Pandoc は、元のソースフォーマットよりも文書構造をよく保持します。変換をビルドステップとして扱い、可逆的なテキストフォーマッターとして扱わないでください。

Hugo サイトのための推奨戦略

Hugo 技術ブログにとって、最も実践的なポリシーは以下の通りです：

1. コアのプローズと構造に CommonMark を使用する。
2. 文書化された小さなセットの Goldmark 拡張機能を有効にする。
3. 可読性を向上させる場所では、GFM スタイルのテーブルとタスクリストを使用する。
4. Mermaid を 1 つの一貫したレンダリングフックまたはショートコードを通じて実装する。
5. 数式を 1 つの文書化された KaTeX または MathJax パイプラインを通じて処理する。
6. Hugo フロントマターは、コンテンツファイルの開始時のみ使用する。
7. 生 HTML よりもレンダリングフックとショートコードを優先する。
8. 可能であれば、ソースリンクを標準の Markdown リンクとして保つ。
9. 移行または外部ソースのドキュメントを Hugo を通してテストする。
10. GitHub で正しくレンダリングされない構文を文書化する。

このアプローチは、Hugo コンテンツが普遍的に移植可能ではないことを受け入れながら、移植性の境界を視覚的に保ちます。

最も悪いアプローチは、意図しない派手の混合です：定義されたビルドパイプラインなしに、同じ文書に GitHub アラート、Obsidian 埋め込み、Pandoc 属性、Hugo ショートコードが配置されること。

決定テーブル

結論

CommonMark、GitHub Flavored Markdown、Pandoc Markdown は、同じ製品の競合バージョンではありません。それらは異なる問題を解決します。

CommonMark は信頼できるパーシングの基盤を提供します。GFM はソフトウェアのコラボレーションのための実用的な機能を追加し、Pandoc Markdown は Markdown をパブリッシングと変換のためのリッチなソース言語に変えます。

最も安全なルールは単純です：実際の目的地を満たす最小の派手で書くこと。コンテンツが移動しなければならない場合は CommonMark、GitHub スタイルのコラボレーションがターゲットの場合は GFM、文書構造と出力形式が普遍的なレンダリングよりも重要の場合は Pandoc Markdown を使用してください。

Markdown の移植性は、すべての拡張機能を避けることで達成されるわけではありません。どの拡張機能がソース契約の一部であるかを理解し、重要なすべてのレンダラーでそれらをテストすることで達成されます。

参考文献

• CommonMark Specification
• GitHub Flavored Markdown Spec
• Pandoc Markdown
• Goldmark Documentation
• Hugo Goldmark Configuration
• Writing Mathematical Expressions on GitHub