Obsidian 的 Markdown：你的檔案、語法，以及哪些帶得走

基礎方言：CommonMark 加上 GFM

在 Obsidian 自己的擴充之前，地基是標準的。Obsidian 遵循 CommonMark 這份多數現代解析器實作的精確規格，再疊上廣受採用的 GitHub 風格 Markdown 擴充。以下這些寫法在 Obsidian 裡的表現，跟在 README 裡完全一樣：

# 標題 1
## 標題 2

**粗體**、*斜體*、~~刪除線~~、`行內程式碼`

- 項目
  - 巢狀項目
1. 編號項目

- [ ] 未完成的待辦
- [x] 已完成的待辦

> 引用區塊

| 欄位 A | 欄位 B |
| ------ | ------ |
| 儲存格 | 儲存格 |

```python
print("帶語言標籤的程式碼區塊")
```

[標準連結](https://mdeditor.tw)
![標準圖片](picture.png)

一句帶註腳的話。[^1]

[^1]: 註腳的內容。

哪些其實是 GFM，不是原始 Markdown

表格、待辦清單、刪除線、自動連結與註腳都來自 GFM 這一層。文字要搬到比較老的工具之前，這點值得先知道。GFM 指南完整說明這個方言，表格指南則處理最容易出錯的那個結構。

第一天就該找出來的設定

在設定裡找嚴格換行（strict line breaks）。它決定單次換行代表什麼。開啟時，Obsidian 照 CommonMark 規格把下一行併回同一段；關閉時，按一次 Enter 就是看得見的斷行。後者寫筆記比較順手，但那不是嚴謹解析器之後會做的事。

小提醒：不確定一則筆記有哪些部分帶得走？把它貼進本站的編輯器。還原樣顯示字元的就是 Obsidian 專屬語法；有渲染出來的大致都帶得走，但有一個但書：數學式與 Mermaid 在這裡和 GitHub 上都會渲染，它們仍屬擴充功能，比較陽春的解析器還是會顯示成文字。

Obsidian 額外加上的語法

這一節全部是 Obsidian 自己的語法。它們真的很好用，但沒有一項是標準 Markdown。含有它們的檔案依然是合法文字檔，只是其他渲染器會把原始字元照樣印出來。

雙向連結與嵌入

[[Project Alpha]]                   以筆記名稱建立連結
[[Project Alpha|Alpha 專案]]        連結但顯示不同文字
[[Project Alpha#目標]]              直接連到某個標題
![[Project Alpha]]                  把整則筆記嵌入本頁
![[Project Alpha#目標]]             只嵌入該段落
![[diagram.png]]                    嵌入 vault 裡的圖片
![[diagram.png|300]]                以 300px 寬度嵌入圖片

連結與嵌入的差別只在前面那個驚嘆號，正好對應標準 Markdown 區分連結與圖片的方式，這點在連結指南裡有完整說明。雙向連結是關係圖與反向連結能運作的原因，重新命名筆記時也不會壞掉，Obsidian 會自動改寫所有引用。

區塊參照

截止日是 3 月 14 日。 ^deadline

之後在任何一則筆記裡：

[[會議記錄#^deadline]]
![[會議記錄#^deadline]]

在區塊結尾加上插入號與識別碼，就標記了那一個段落、清單項目或表格，讓它可以被單獨連結或嵌入。透過 Obsidian 的連結選單建立參照時，產生的會是一組隨機短字串，而不是好讀的名稱。

標註區塊 callout

> [!note] 可自訂的標題
> 標註區塊的內文寫在這裡。

> [!warning]- 預設收合
> 加上減號代表預設收合，
> 加上加號則是可收合但預設展開。

類型包含 note、tip、info、todo、success、question、warning、failure、danger、bug、example、quote 等，各有顏色與圖示。標註區塊有個很棒的特性：它建立在引用語法之上，所以完全不認得它的工具仍會渲染出合理的結果。

標籤與註解

#project  #project/alpha  #reading/2026

%%這段文字在閱讀模式看不到。%%

%%
多行註解的寫法也一樣。
%%

標籤直接寫在行內，井字號後面不能有空白，斜線可以做出階層。用兩個百分比符號包住的註解在閱讀模式會隱藏，但仍留在檔案裡，很適合寫給自己看的備註。

注意：同一個字元在這裡身兼兩職。#project 沒有空格是標籤，# project 有空格則是一級標題。寫反了，一個安靜的標籤就會變成巨大的大標。

YAML 前置資料與屬性

檔案最開頭用三個連字號圍住的區塊，就是 YAML 前置資料。它必須是筆記的第一個東西，上面不能有任何內容。Obsidian 會讀取它並以屬性面板呈現：

---
title: 每週回顧
tags:
  - review
  - planning
aliases: [週回顧, 回顧筆記]
date: 2026-03-14
published: false
---

# 每週回顧

筆記內文從這裡開始。

本來就有意義的幾個鍵

屬性值是有型別的：日期就以日期的方式運作，核取方塊是布林值。有兩個鍵直接接進了程式本身：

• tags 與行內井字標籤共用同一套系統，兩種寫法會出現在同一份搜尋結果裡。
• aliases 讓一則筆記能以多個名稱被搜尋，也能被多個名稱連結。

檔案裡風險最低的非標準語法

前置資料不屬於 CommonMark，但它也不是 Obsidian 發明的。Hugo、Jekyll、Astro 等靜態網站產生器要的正是這個區塊，這也是 vault 能直接當部落格素材的原因。不認得它的渲染器通常會隱藏它，或顯示成一個小表格，所以筆記搬家時幾乎沒有損失。

數學公式與流程圖

用錢字號寫數學式

Obsidian 透過 MathJax 渲染 LaTeX 數學式。前後各一個錢字號是行內公式，各兩個則是置中的獨立區塊：

行內：把 $a^2 + b^2 = c^2$ 這個式子放進句子裡。

$$
\frac{d}{dx} e^{x} = e^{x}
$$

以文字形式保存的流程圖

流程圖使用語言標籤為 mermaid 的程式碼區塊，圖表因此是以可讀文字存在檔案裡，而不是一張圖片。這用的正是程式碼區塊在各處都通用的語言標籤機制：

```mermaid
graph TD
  A[粗略想法] --> B[永久筆記]
  B --> C[發佈的文章]
```

兩者都是擴充而非核心 Markdown，但外部支援度意外地好：GitHub 會渲染 Markdown 檔裡的 Mermaid 區塊與錢字號數學式，用到它們的筆記搬進版本庫後往往仍然完整。本站的編輯器同樣支援，數學式交給 KaTeX、流程圖交給 Mermaid，推上任何平台前拿它先確認一遍很方便。其他輕量預覽窗格則會把它當成一般程式碼區塊顯示，那是優雅的降級，而不是壞掉的檔案。

哪些帶得走、哪些帶不走，以及怎麼保持可攜

以下是誠實的支援對照表。最後一欄是 Obsidian 以外的 CommonMark 或 GFM 渲染器會讓讀者看到的結果：

會壞掉的語法，先講解法

先動那個開關：進入設定 → 檔案與連結，關掉使用 Wiki 連結的選項，新連結就會改用標準寫法 [Note](Note.md)。旁邊的「新連結格式」請選相對路徑，因為檔案搬出 vault 之後，相對路徑活下來的機率比絕對路徑高。

真正會壞的只有標示為「否」的那幾列，其中最痛的是雙向連結，因為連結正是筆記系統的核心。其餘語法都是溫和降級：標註變成引用、標籤變成文字、註解變成可見。內容不會遺失，只是看起來樸素一點。

注意：這個設定只影響之後建立的連結。vault 裡既有的每一組 [[雙中括號]]，在你動手改寫之前都不會變。

把現有的 vault 改成可攜

1. 先關掉 Wiki 連結，讓之後寫的每一個連結都是標準寫法。
2. 再一個資料夾一個資料夾，把既有的雙中括號連結改寫掉。
3. 把 ![[image.png]] 嵌入換成 ![替代文字](image.png)。
4. 決定哪些標註值得保留成一般引用區塊，其餘壓平成普通段落。

筆記嵌入完全沒有標準對應，所以第三步是工作量最大的一步。如果圖片對你很重要，圖片指南說明了可攜的寫法，以及隨之而來的替代文字規則。

用別的編輯器打開你的 vault

VS Code、GitHub 與一個瀏覽器分頁

既然 vault 只是資料夾，你隨時能在別處打開它。把 VS Code 指向這個資料夾，就有語法高亮、跨檔搜尋與 Git。把資料夾推上 GitHub，每則筆記都會渲染成網頁，雙向連結則以字面文字出現。把筆記丟進本站的編輯器，標準語法會即時預覽出來，數學式與 Mermaid 區塊也一樣。

如果筆記最後要變成網站

這件事請提早規劃。要「只寫可攜的子集合」，還是「加一道轉換流程」，得先決定，因為多數靜態網站產生器在建置前都得先改寫雙向連結與嵌入語法。如果筆記只給自己看，那就盡情使用所有功能；帳單只在你離開的那一刻才會送到。

寫作時建議開著兩份參考：標準語法看語法速查表，背後的細節看完整指南。還在猶豫寫哪種方言的話，該選哪種 Markdown 方言是最短的答案。

聊天與論壇工具又是另一套規則。同一則筆記貼進 Discord 會失去表格，貼上 Reddit 則會失去單一換行。平台總覽把各家的差異並排列在一起。