連結驗證與嚴格模式

頁面改名或搬移後，連結很容易在不知不覺中失效。Zensical 會在建置時掃描每一個 Markdown 檔案，驗證所有內部連結（行內連結與參考式連結），包含錨點是否存在。搭配嚴格模式，還可以在發現問題時中止建置。

編輯時就發現問題

Zensical Studio 可以在編輯器裡就即時檢查連結，並在標題改名或檔案搬移時自動更新連結，不必等到建置才發現。

預設行為

連結驗證預設就是啟用的，你只需要照常寫內容。有問題時會顯示警告，包含檔名、行號與說明：

$ zensical build
...
Warning: page does not exist
   ╭─[ index.md:3:14 ]
   │
 3 │ [this page]: non-existent.md
   │              ───────┬───────
   │                     ╰───────── page does not exist
───╯

可設定的檢查項目

[project.validation]
invalid_links = true
invalid_link_anchors = true
unresolved_references = false
unresolved_footnotes = false
unused_definitions = false
unused_footnotes = false
shadowed_definitions = false
shadowed_footnotes = false

檢查	預設	什麼時候警告
`invalid_links`	開	連結指向不存在的頁面
`invalid_link_anchors`	開	連結指向不存在的錨點（`#xxx`）
`unresolved_references`	關	連結／圖片的參考式定義找不到
`unresolved_footnotes`	關	註腳引用找不到對應的定義
`unused_definitions`	關	連結定義從未被引用
`unused_footnotes`	關	註腳定義從未被引用
`shadowed_definitions`	關	同一個連結定義重複宣告
`shadowed_footnotes`	關	同一個註腳定義重複宣告

後六項已經標示為棄用

這六個檢查目前仍可使用，但因為方法無法涵蓋許多特殊情況，官方已標示為棄用，之後會用功能相同、但更可靠的新檢查取代。

完全關閉驗證：

[project]
validation = false

跳脫方括號

如果你只是想用方括號把一段文字框起來，而不是建立連結，請在左括號前加上反斜線 \[（右括號不需要跳脫）：

這不是 \[連結](https://example.com)。

驗證會假設方括號中的文字都是連結或註腳，所以沒有跳脫的話，可能會產生不必要的警告。

嚴格模式（Strict mode）

平常發現問題只會警告。啟用嚴格模式後，建置會在回報所有問題之後中止，並且以結束代碼 1 表示失敗，很適合放在 CI/CD 流程中，確保上線前所有連結都正常。

用命令列選項：

zensical build --strict

或者讓專案永遠以嚴格模式建置：

[project]
strict = true

輸出範例：

$ zensical build --strict
...
Warning: anchor does not exist
   ╭─[ index.md:5:27 ]
   │
 5 │ [link target is missing](#undefined)
   │                           ────┬────
   │                               ╰────── anchor does not exist
───╯
1 issue found
Aborted because --strict flag is set

在 GitHub Actions 裡，只要把建置指令改成 zensical build --clean --strict，就能在連結壞掉時阻止佈署。

總結

想做的事	做法
檢查失效連結	預設啟用，看建置警告
開啟／關閉某項檢查	`[project.validation]`
完全關閉	`validation = false`
有問題就讓建置失敗	`--strict` 或 `strict = true`
讓方括號不被當成連結	`\[`

參考資料

Validation - Zensical