GFM、CommonMark、Pandoc Markdownの比較：構文の違い

マークダウンは、GitHub、Hugo、Obsidian、Pandocで同じファイルが異なる方法でレンダリングされるまで、一貫した言語のように見えます。問題なのはマークダウンが信頼できないという点ではありません。

「マークダウン」とは、単一の普遍的なドキュメントフォーマットではなく、関連する構文、パーサー、プラットフォーム機能の一群を指す用語だからです。CommonMarkは正確でポータブルなコアを定義し、GitHub Flavored Markdownはソフトウェア協業に有用な機能を追加し、Pandoc Markdownは言語を本格的なドキュメント作成フォーマットへと拡張します。

どちらを選ぶかは、ドキュメントをどこでレンダリングするかによって決まります。READMEファイル、Hugoのブログ投稿、学術論文はそれぞれ異なる要件を持っています。この比較は、より広範なドキュメンテーションツールの文脈の一部であり、正式な方言、プラットフォーム固有の拡張、実用的なポータビリティルールをカバーし、ターゲット環境に適した構文を選べるようにします。構文のクイックリファレンスとして、マークダウンチートシートでは必須のフォーマット要素を網羅しています。

マークダウンは単一の言語ではない

オリジナルのマークダウン構文は、意図的に小さく、緩やかに指定されていました。これにより読みやすく、実装も容易になりましたが、異なるパーサーが曖昧な入力を異なる方法で解釈し始めました。

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

Pandoc Markdownは異なるアプローチを取ります。小さくWeb指向の構文にとどまる代わりに、引用、メタデータ、脚注、定義リスト、属性、数学表記などのドキュメント機能を追加します。

簡略化した関係は以下のようになります。

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

簡潔な結論

ポータビリティが最も重要である場合は、CommonMark互換の構文を使用します。

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

ソースドキュメントをPDF、DOCX、EPUB、LaTeX、スライド、または引用とメタデータ付きの学術論文にする必要がある場合は、Pandoc Markdownを使用します。

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

意見のある見解: Hugoの技術ブログで覚えておくべきルールが一つだけ 있다면、CommonMarkとGFMスタイルのテーブル、タスクリストをデフォルトとし、それ以外（脚注、数学式、コールアウト、ヘッダー属性など）は、デフォルトではなく明示的でテスト済みの拡張機能として扱います。この一つの習慣が、以下に説明されているポータビリティ失敗の大部分を防ぎます。

CommonMark: ポータブルなコア

CommonMarkは基本的なマークダウン言語の正式な仕様です。その主な貢献は機能の大規模なコレクションではなく、一貫した解析にあります。

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

• 段落
• 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.

この種のドキュメントは、ほぼすべての現代のマークダウン環境で動作します。見出し、段落、リスト、フェンス付きコード、通常のリンクを使用しており、方言固有の拡張機能に依存していません。

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

GitHub Flavored MarkdownはCommonMarkに基づく正式な方言です。CommonMarkの解析モデルを維持し、リポジトリドキュメントや協業で一般的に必要な機能を追加します。

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

• パイプテーブル
• タスクリスト項目
• 取り消し線
• 拡張自動リンク
• 一部の生HTMLタグに関する制限

これらの拡張機能は現在非常に一般的であり、多くのユーザーはそれらが標準マークダウンの一部だと考えています。しかし、それらはCommonMarkコアの一部ではありません。

GFMテーブル

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

厳格なCommonMarkパーサーは、これを通常の段落テキストとして扱うことを許可されています。GFM互換パーサーはこれをテーブルとして認識します。テーブル構文と配置オプションの詳細については、マークダウンでのテーブルを参照してください。

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>

明示的な形式は、ドキュメントが未知のマークダウンプロセッサを通過しなければならない場合に安全です。

GitHub.comは正式なGFM以上の機能をサポート

混乱の頻繁な原因は、GitHubで表示されるすべてのマークダウン機能がGFM仕様に属すると仮定することです。

そうではありません。

GitHub.comは、GFMパーサーの周りにプラットフォームレベルの処理と機能を追加します。文脈に応じて、GitHubは以下をサポートできます：

• 数学式
• Mermaidダイアグラム
• アラート
• イシューおよびプルリクエストの参照
• ユーザーおよびチームメンション
• コミット参照
• イmojiショートコード
• 折りたたみ可能なHTMLセクション
• カラープレビュー
• リポジトリ相対リンク
• 自動見出しアンカー

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

この区別は重要です。他のレンダラーは、GFM互換性を正確に主張しながらも、GitHubの数学レンダラー、Mermaid統合、イシュー参照、アラートスタイルを実装していない可能性があります。

GitHub Mermaidダイアグラム

GitHubはmermaidでマークされたフェンス付きコードブロックをダイアグラムとしてレンダリングします：

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

一般的なGFMレンダラーは、同じブロックをシンタックスハイライトされたソースコードとして表示する場合があります。マークダウンは依然として有効ですが、拡張されたレンダリングはプラットフォーム固有です。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: ドキュメント言語としてのマークダウン

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

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

• 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は現在、いくつかのコンテンツ文脈で脚注をレンダリングしていますが、それは正式なGFMの保証ではなくGitHubプラットフォームの機能です。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のリーダー側の柔軟性は、逆方向の変換ワークフローも支えています — Wordドキュメントをマークダウンへの変換は、Pandocの拡張方言を中間フォーマットとして使用するための実用的な例です。

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は中括弧を明示的な識別子とクラスリストとして解釈します。他の多くのマークダウンレンダラーは、属性テキストをそのまま見出しに表示します。

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

Pandocフェンス付き分割

::: warning
Changing this option restarts the server.

Pandocはこれをクラス付きの構造的分割に変換します。テンプレート、CSS、フィルター、または出力ライターがその構造をどのように表示するかを決定できます。

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

CommonMark vs GFM vs Pandoc Markdown

以下のマトリクスは、正式な方言を記述しています。GitHub.com、Hugo、Obsidian、GitLab、または他のプラットフォームが追加したすべての機能ではありません。

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

GitHubで動作する構文は？

READMEファイル、イシュー、プルリクエスト、ディスカッション、Wikiには、GFMが自然な基準です。

一般的に以下を使用できます：

• CommonMark構文
• テーブル
• タスクリスト
• 取り消し線
• 拡張自動リンク
• シンタックスハイライトされたコードフェンス
• GitHub固有の参照
• GitHubサポートされた数学
• GitHubサポートされたダイアグラム
• GitHubアラート
• コンテンツサーフェスがサポートする脚注

ポータビリティリスクは、GitHubが正式なGFMを超えて追加のレンダリングを開始したときに始まります。Mermaidダイアグラム、数学表記、イシュー参照、アラートプレゼンテーションは、GitHub外では生存しない可能性があります。

他の場所でも公開されるリポジトリファイルについては、GitHubプレビューを権威あるものとして扱うのではなく、2番目のレンダラーでソースをテストしてください。

Hugoで動作する構文は？

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

典型的なHugo構成では、以下がうまく動作します：

• CommonMark構造
• フェンス付きコードブロック
• パイプテーブル
• 取り消し線
• タスクリスト
• 自動見出しID
• シンタックスハイライト
• 拡張機能が有効な場合の脚注
• 有効な場合の定義リスト
• 有効な場合のタイポグラフィック置換

Hugoはまた、以下のマークダウン外に機能を追加します：

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

これらのHugo機能はマークダウンファイルと一緒に移動しません。Hugoデプロイメントの実用的な例については、Deploy Hugo to AWS S3を参照してください。

Hugoフロントマターはマークダウンコンテンツではない

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は、いくつかのマークダウン方言を明示的に読むことができます：

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」が常に一つの固定構成ではないことを意味します。ビルドコマンドとデフォルトファイルはドキュメント仕様の一部です。

Obsidianで動作する構文は？

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

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

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

このようなWikiリンク：

[[Markdown Compatibility]]

はObsidianバウト内の意味があります。GitHub、CommonMark、およびデフォルトのPandocリーダーは、通常、リテラルな角括弧テキストとして表示します。

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

![[compatibility-table]]

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

Obsidianは、.mdファイルでのストレージがマークダウンのポータビリティを保証しない理由の良い例です。知識管理ツールとしてのObsidianの実践的な見解については、Obsidian for Personal Knowledge Managementを参照してください。

GitLabで動作する構文は？

GitLab Flavored MarkdownはCommonMarkをコアとして使用し、テーブルやタスクリストなどのGFM機能を含みます。その後、クロス参照、数学表記、ダイアグラム、その他の協業機能などのGitLab固有の振る舞いを追加します。

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

プラットフォーム統合は同じほど信頼できません。イシュー参照、ユーザーメンション、ダイアグラム、数学処理、特殊ブロック構文は、基本的なマークダウンが依然として読み取り可能でも、異なる振る舞いをすることがあります。

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

このマトリクスは一般的なデフォルト動作を記述しています。テーマ、プラグイン、拡張、構成は個々のセルを変更できます。

「Yes」は依然として同じ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.

視覚的には印象的ではありませんが、どこでも意味を保持します。

Wikiリンク

Wikiリンクは知識管理ツール内で簡潔です：

[[KV Cache]]

ターゲットパス、ファイル名、見出しルール、および解決動作がアプリケーションに属するため、交換構文としては劣っています。

公開を意図したコンテンツでは標準的なマークダウンリンクを使用します：

[KV cache](kv-cache.md)

生HTML

生HTMLは、マークダウンがレイアウトを表現できない場合の通常の回避策です。また、ポータビリティとセキュリティの失敗も一般的です。

レンダラーは以下を行う可能性があります：

• HTMLを削除
• エスケープ
• 選択された要素をサニタイズ
• ブロックは許可するがインライン要素は許可しない
• HTML内のマークダウン解析を拒否
• 信頼されたモードでのみ変更なしで渡す

生HTMLは、発行ターゲットが制御されている場合にのみ使用してください。

数学表記

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

ソース：

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

以下になる可能性があります：

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

一つの数学パイプラインを選び、すべてのターゲット環境でテストします。

Mermaidおよび他のダイアグラムブロック

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

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

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

マークダウン互換性の3つのレイヤー

互換性を3つのレイヤーに分離すると役立ちます。

レイヤー1: 解析互換性

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

例には見出し、テーブル、脚注、フェンス付き分割が含まれます。

レイヤー2: 変換互換性

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

例には以下が含まれます：

• Mermaidのレンダリング
• 引用の解決
• Wikiリンクの展開
• イシュー番号のリンク
• ショートコードの処理
• 目次の生成

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

結果は適切に見え、振る舞いますか？

例には以下が含まれます：

• テーブルスタイル
• シンタックスハイライト
• アラートカラー
• 見出しアンカー
• レスポンシブ画像
• 脚注の配置
• 数学フォント

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

より良いポータビリティモデル

ファイルが「有効なマークダウン」かどうかを問う代わりに、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

この説明は、「サイトがマークダウンを使用している」と言うよりもはるかに有用です。

使用ケースによる方言の選択

READMEファイル

GFMを使用します。

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

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

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

Hugo技術記事

文書化されたGoldmark拡張セットを持つCommonMark互換のマークダウンを使用します。

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

Hugo固有の構文を分離し、見つけやすい状態に保ちます。

学術ドキュメント

Pandoc Markdownを使用します。

引用、参考文献処理、脚注、メタデータ、数学表記、クロス参照、およびPDFまたはDOCXへの变換は、ポータビリティの低下を正当化します。

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

書籍および長文ドキュメンテーション

複数の出力フォーマットが重要な場合、Pandoc Markdownは通常3つのオプション中最強です。

定義リスト、引用、属性、メタデータ、構造化変換は、ドキュメントの複雑性が成長するにつれてより重要になります。

GitリポジトリでホストされているWeb専用のドキュメンテーションでは、GFMまたはCommonMarkベースのドキュメンテーションジェネレーターが依然として単純かもしれません。

メモおよび個人知識ベース

アプリケーション機能が真の価値を提供する場合、選択されたメモアプリケーションのネイティブ構文を使用します。

ObsidianのWikiリンク、埋め込み、コールアウトはバウト内で有用です。エクスポートをコンパイルプロセスとして扱い、生ファイルがすでにポータブルな出版物であると仮定しないでください。

未知のシステム間の共有ドキュメンテーション

保守的なCommonMarkサブセットを使用します。

以下を避けます：

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

ポータビリティは通常、利便性機能を手放すことを必要とします。

ポータブルマークダウンの実践的ルール

CommonMark構造から始める

ドキュメントスケルトンにCommonMarkを使用します：

• 見出し
• 段落
• リスト
• リンク
• 画像
• ブロック引用
• コードブロック

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

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

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

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

プラットフォーム拡張を隔離する

プラットフォーム固有の構文を明確に識別できるブロックに保持します。

例えば、Hugoショートコード、Pandoc引用、またはObsidian埋め込みを各段落に散らばせるのではなく、中央に集約します。

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

優雅な劣化を優先する

Mermaidブロックは読み取り可能なソースコードに劣化します。GitHubアラートはブロック引用に劣化します。

Wiki埋め込みは説明のないファイル名に劣化する可能性があり、Pandocフェンス付き分割はコンテンツの周りに句読点を暴露する可能性があります。

フォールバックが依然として理解できる拡張機能を選択します。

自動生成された見出しIDに依存しないでください

見出しアンカーアルゴリズムはGitHub、Hugo、Pandoc、およびドキュメンテーションジェネレーター間で異なります。

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

ビルド構成をコンテンツと一緒に保持する

Pandoc拡張、Hugo設定、プラグイン、フィルター、およびJavaScript統合は、マークダウンがどのように振る舞うかを決定します。

関連する構成ファイルをソースと一緒にコミットします：

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

.md拡張名だけでは、発行環境をキャプチャしません。これらの決定を文書化するための構造化されたアプローチについては、Decision Records for AI-Driven Developmentを参照してください。

重要なすべてのターゲットに対してマークダウンをテストする

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のローカルマークダウン拡張は、GitHubまたはGitLabと一致しない可能性があります。

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

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

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

ポータブルサブセットをLintする

マークダウンリンターはレンダラー互換性を保証できませんが、回避可能な曖昧さを削除できます。

有用なルールには以下が含まれます：

• 一貫した見出しスタイルを使用
• リストとコードブロックの周りに空行を追加
• インデントされたコードではなくフェンス付きコードを使用
• コードフェンス言語を指定
• 飛ばされた見出しレベルを避ける
• 一貫したリストマーカーを使用
• 句読点の周りに曖昧な強調を避ける
• 行末を一貫させる
• リンクと画像を検証

マルチターゲット出版では、構文Lintにのみ依存するのではなく、各重要なレンダラーのビルドテストを追加します。

Pandocで方言間を変換する

Pandocは、一方の方言から他方へドキュメントを正規化できます：

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. 可能な限り標準的なマークダウンリンクとしてソースリンクを保持します。
9. 移行または外部ソースのドキュメントをHugoを通じてテストします。
10. GitHubで正しくレンダリングされない構文を文書化します。

このアプローチは、Hugoコンテンツが普遍的にポータブルではないことを受け入れながら、ポータビリティ境界を可視に保ちます。

最悪のアプローチは、定義されたビルドパイプラインなしでGitHubアラート、Obsidian埋め込み、Pandoc属性、Hugoショートコードを同じドキュメントに配置する偶然の方言混合です。

決定テーブル

結論

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

CommonMarkは信頼できる解析基盤を提供します。GFMはソフトウェア協業に実用的な機能を追加し、Pandoc Markdownはマークダウンを出版と変換のためのリッチなソース言語に変えます。

最も安全なルールは単純です：実際の目的地を満たす最小の方言を書きます。コンテンツが移動しなければならない場合はCommonMarkを、GitHubスタイルの協業がターゲットの場合はGFMを、ドキュメント構造と出力フォーマットが普遍的なレンダリングよりも重要な場合はPandoc Markdownを使用します。

マークダウンのポータビリティは、すべての拡張機能を避けることで達成されるわけではありません。どの拡張機能がソース契約の一部であり、重要なすべてのレンダラーでそれらをテストすることで達成されます。

参考文献

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