Notion・Obsidian・GitHubで活きるMarkdown活用術

Notion、Obsidian、GitHubは、どれも「Markdownで書ける」とうたっていますが、実際に同じ文章を3つのツール間でコピー&ペーストしてみると、驚くほど挙動が違います。太字のはずが斜体になる、見出しのつもりがタグになる、リンクがただの文字列に化ける——。手元のメモをあちこちのツールへ移し替えるたびに何度もハマってきた、具体的な「記法の差」と「つまずき所」を、実際のMarkdownの書き方と一緒にまとめておきます。

まず結論：「Markdown対応」の中身は統一されていない

「Markdown対応」と一口に言っても、各サービスが実装しているのは独自に拡張された方言のようなものです。基本の # や - はほぼ共通ですが、そこから先の挙動は次のように割れます。

記法	Notion	Obsidian	GitHub
`# 見出し`	H1〜H3のみ対応（H4以降は太字扱い）	H1〜H6すべて対応	H1〜H6すべて対応
`[[ノート名]]`	認識されず文字列のまま	ノート間リンクとして機能	認識されず文字列のまま
`- [ ] タスク`	チェックボックスに変換	チェックボックスに変換	チェックボックスに変換（操作できるのはIssue/PR上のみ）
`#タグ`	ハッシュタグ機能なし（見出し記法と混同しやすい）	インラインタグとして機能	`#` の後に数字が続くとIssue/PRリンクに誤認識される（`#議事録`のような文字列は無反応）
`> [!NOTE]`	認識されず引用のまま	コールアウトに変換	GitHub独自のアラートに変換（対応キーワードが別）

以下、それぞれの差で実際につまずいたポイントを見ていきます。

Notionでハマった「見出しレベル」の壁

Notionは入力中に # を打つとその場で見出しに変換してくれて便利ですが、対応しているのはH1〜H3までです。

# 大見出し
## 中見出し
### 小見出し
#### これはNotionでは見出しにならない

他のツールで ####（H4）以下まで使って階層を作り込んだ文書をNotionに貼り付けると、H4以下の行は見出しではなく、ただの太字テキストとして扱われます。仕様書のようにH4・H5まで作り込んだMarkdownをNotionへ移すときは、事前にH3までに構成を圧縮しておかないと、貼り付けた瞬間に階層構造が崩れて見えることになります。

Obsidianの「#」は見出しにもタグにもなる

Obsidianで最初に混乱したのは、# の直後にスペースがあるかどうかで意味がまったく変わることでした。

# 議事録
#議事録

1行目の # 議事録（# の後ろに半角スペースあり）はふつうの見出しになりますが、2行目の #議事録（スペースなし）はObsidian独自の「タグ」として認識され、タグ一覧やグラフビューに登録されます。標準的なMarkdownの感覚では「スペースを打ち忘れただけの見出し」のつもりが、Obsidianの中では見出しではなくタグという別の機能に化けてしまうわけです。日本語入力からスペースを打ち忘れやすい人ほど、意図せずタグだらけのノートを量産してしまいます。

もう一つObsidianに特有なのが [[ノート名]] というダブルブラケットのリンク記法です。

関連メモは[[プロジェクトA議事録]]を参照。

これはObsidian内では自動でノート同士をつなぐリンクになり、リンク先のノート名を変更すると参照側の表記も自動で追従してくれる便利な機能です。ただしこの [[...]] は標準のMarkdownリンク記法（[表示文字](URL)）とは別物で、GitHubやNotionに同じ文章を貼り付けると、ただ「[[プロジェクトA議事録]]という文字列」としてそのまま表示されてしまいます。Obsidianで書いたノートをそのまま社内Wikiやドキュメント化ツールへ移すときは、この二重角括弧のリンクを標準リンクに書き直す作業がほぼ必須になります。

GitHubの「アラート構文」はObsidianのコールアウトと似て非なるもの

GitHubのMarkdown（READMEやIssueなど）には、注意書きを目立たせる「アラート」という構文があります。

> [!NOTE]
> ここは補足情報です。

> [!WARNING]
> ここは警告です。

見た目がObsidianの「コールアウト」構文（ブロック引用の先頭に > [!note] のようにタグを指定する書き方）とほぼ同じなので、最初は同じ機能だと思い込んでいました。しかし対応しているキーワードと、未対応キーワードに出会ったときの挙動が異なります。GitHubは NOTE TIP IMPORTANT WARNING CAUTION の5種類にしか対応しておらず、それ以外の [!XXX] は装飾されず「[!XXX] という文字列を含む、ただのブロック引用」としてそのまま表示されます。一方Obsidianは note tip warning info success など、プラグインなしでも標準で十数種類のコールアウトに対応しており（たとえば important は tip の公式エイリアスとして扱われ、ちゃんとコールアウトとして描画されます）、さらに対応表にないキーワードを指定した場合でも引用に戻ることはなく、既定の note タイプのコールアウトとして表示されます。つまりGitHub用に書いた > [!IMPORTANT] はObsidianでもコールアウトとして描画される一方、Obsidian独自のコールアウトをGitHubのREADMEに貼ると、対応する5種類以外は装飾が反映されず [!XXX] の文字列ごと引用として表示されてしまう、という非対称な関係になっています。

チャットツールの「強調」はさらに別ルール

SlackやDiscordのような日常のチャットツールも一見Markdownっぽい記法を使いますが、太字の書き方が異なります。

Notion / Obsidian / GitHub: **太字**
Slack: *太字*

標準的なMarkdownでは太字は **（アスタリスク2つ）ですが、Slackでは *（1つ）で太字になり、** はむしろそのまま記号として表示されてしまいます。逆にSlackで書いた *重要* をNotionやGitHubにそのまま貼ると、太字ではなく斜体として解釈されます。チャットでのメモをそのまま議事録用のMarkdownファイルに転記するときは、強調記号を書き直す一手間が必要になる、という地味だけれど頻発するつまずきです。

結局どう付き合えばいいか

ここまでの違いを踏まえると、複数ツールをまたいでMarkdownを使うときに意識しておきたいのは次の3点だと感じています。

見出しは各ツールの最大階層（Notionなら H3まで）に合わせて浅めに設計しておく
[[...]] やタグ、コールアウトのようなツール固有の拡張記法は、他ツールへ持ち出す前提のメモには極力使わない
強調記号（* と **）はコピー元とコピー先で必ず見比べて直す

自分の場合、Wordや仕様書などもとがMarkdownでない資料は、いったんshiyoshoで標準的なMarkdownに変換してから、上記のようなツール固有の記法を手直しして使い分けています。ゼロから各ツールの方言を覚えるより、まず標準の形にそろえたうえで行き先のツールに合わせて数カ所だけ調整する方が、結果的に手間が少ないと感じています。