「記事」のような全角の日本語は、等幅フォントで英数字の2文字分の幅を占める — この違いが、ASCIIの文字数だけを基準にそろえたMarkdownの表を、日本語混じりの文章では見た目が崩れて見せる原因になる。
基本構文
# 見出し—#文字の数に応じた異なるレベルの見出し。**太字**と*斜体*— テキストの強調。[テキスト](url)— リンク。- 項目または1. 項目— 箇条書きと番号付きリスト。- ``` — 言語名に基づくシンタックスハイライト付きコードブロック。
全角文字がGFMの表を崩す理由
GitHub Flavored Markdown(GFM)の表は、ソース上でパイプ|の位置さえ揃っていれば正しくレンダリングされる仕様だが、多くのエディタのプレビュー機能はソースの見た目を等幅で整列させようとする。半角英数字は1文字1カラム幅として扱われる一方、ひらがな・カタカナ・漢字は視覚的に2カラム分の幅を持つため、日本語と英数字が混在するセルではソース上の見た目の整列が意図せず崩れる — レンダリング結果自体は正しくても、編集中の生テキストが読みにくくなる典型的な原因である。
オリジナルのMarkdownには表もCommonMarkも存在しなかった
John Gruberが2004年に公開したMarkdownは散文による説明であり、厳密な文法ではなかった。表も取り消し線も、言語指定付きのコードブロックも定義されていなかった。10年間、各実装がオリジナルの記述があいまいにしていた部分をそれぞれ独自に解釈し続けた末、2014年にCommonMarkが厳密な文法を定め、その上にGitHub Flavored Markdown(GFM)が表やタスクリストといった、今ではどのREADMEでも当たり前に使われる拡張を追加した。
HTMLへの変換とその逆
Markdown → HTMLの変換は直接的です: パーサーが構文構造を認識し、対応するタグを生成します。逆の変換、HTML → Markdownはより困難です。HTMLは基本的なMarkdownよりもはるかに多くの書式オプションをサポートしているため、一部のマークアップ（複雑な表、ネストしたスタイル）は簡略化されたり失われたりする可能性があります。
この機能が必要な理由
- 公開せずにMarkdownファイルがどうレンダリングされるかを素早くプレビューする。
- バージョン管理システムに保存するためにページやドキュメントのコンテンツをMarkdownに変換する。
- Markdownのみを受け入れるアプリに挿入するためにHTMLコンテンツを準備する。