利用 Travis-CI 為你的文章增加 Markdown 寫作規範檢查

Wi1dcard發表於2019-01-26

hustcc/lint-md 是一款中文 Markdown 寫作規範檢查工具，檢查規則來源於 ruanyf/document-style-guide。

配合 CI/CD 使用，即能夠以完全自動化的方式，確保優秀的博文質量，長期使用還可培養良好的寫作習慣。

準備

首先，我們需要熟悉該工具。

# 全域性安裝
npm install -g lint-md
# 使用方法如下
lint-md <files> [--config <config_file>]
  • files 為一個或多個需檢查的檔案路徑。
  • config_file 為 JSON 格式的配置檔案路徑。

其配置檔案格式如下。

{
  "excludeFiles": [], // 忽略的檔案或目錄列表
  "rules": {
    "no-empty-code": 1 // 定義規則告警級別
    // ...
  }
}

no-empty-code 為規則名稱，其值與告警級別的對應關係如下：

  • 0: Ignore 忽略，不檢查該規則
  • 1: Warning 警告，但程式退出碼不受影響，依舊為零
  • 2: Error 錯誤，退出碼非零，「通常」會中斷 CI 流程，為何「通常」詳見下文

過程

官方文件提供了一套 Travis 的配置。

language: node_js
node_js:
  - "10"
before_install:
  - npm i -g lint-md
script: lint-md README.md

對於我的部落格已經大量使用 Node.js，且包含 package.json，我更傾向於使用以下的配置，而不是全域性安裝：

language: node_js
node_js:
  - "10"
install:
  - npm install
  - export PATH=$PATH:$(pwd)/node_modules/.bin
script: lint-md source/_posts/* --config lint-md.json # 適用於 Hexo 部落格

可以看到，我使用 npm install 命令安裝所有 package.json 中宣告的依賴，隨後將 node_modules/.bin 目錄追加至 PATH 環境變數。

這樣，只需執行一次 npm install，在新增後續依賴時統一宣告在 package.json 即可，保持配置檔案簡略易讀。

另外，修改 $PATH 是為了達到與全域性安裝統一的效果。即在使用依賴的可執行檔案時，無需 ./node_modules/.bin/foo-bar 而只要 foo-bar。

source/_posts/* 是 Hexo 部落格預設的 Markdown 文章原始碼目錄，lint-md.json 是我自己建立的配置檔案，內容如下：

{
    "excludeFiles": [],
    "rules": {
      "no-empty-code-lang": 0,
      "no-trailing-punctuation": 0
    }
}

該配置檔案可根據你的需要自定義，以上忽略的兩個規則是我認為沒什麼必要的，僅供參考。

另外需要注意的一點是，根據 Travis-CI 中對於 Job Lifecycle 的文件描述：

If any of the commands in the first four phases of the job lifecycle return a non-zero exit code, the build is broken:
If before_install, install or before_script returns a non-zero exit code, the build is errored and stops immediately.
If script returns a non-zero exit code, the build is failed, but continues to run before being marked as failed.

也就是說，如果你的 Travis 配置檔案像這樣，在 script 內有多條命令：

language: node_js
node_js:
  - "10"
install:
  # ...
script:
  - lint-md
  - hexo generate
  - hexo deploy
  # ...

那麼如果 lint-md 失敗後，雖然返回了非零的退出碼，但 hexo generate 以及 hexo deploy 等後續命令依舊會執行！只不過流程結束後會標記該 Job 為失敗（Failed）狀態。

也就是說，如果你的 Markdown 中存在不規範的文字，被 lint-md 檢出錯誤後，後續的生成和部署流程依舊會照常執行！這就達不到「存在問題則不釋出」的效果了。針對這個問題，解決方案有二：

其中，移動到 before_script 會造成一個微小的影響 —— 若命令執行返回非零退出碼，那麼該 Job 會被立即標記為錯誤（Error）狀態並停止執行，而非失敗（Failed）狀態。請注意 Travis-CI 中這點小區別。

問題

目前該專案還不夠完善，參見：

Issue #33, #34。

擴充

當然，該工具也可以本地使用，還具備 --fix 選項，能夠自動修復不符合規範的文字。

另外，dkhamsing/awesome_bot 是一款驗證檔案內 URL 是否有效的工具。原本用於各類 awesome 專案檢查其連結、以及收到 PR 時，自動檢查包含的 URLs 是否可訪問。同樣，也可以給 Markdown 部落格使用，能夠確保博文內的連結可用。

雖然，我在本地使用該工具對所有文章的連結可用性進行了一遍「普查」，但我決定不在 CI 流程內加入該工具。主要由於配置項不夠豐富，部分連結我「確實」希望它失效，但無法忽略某檔案中某一特定連結。

本作品採用《CC 協議》，轉載必須註明作者和本文連結
Former WinForm and PHP engineer. Now prefer Golang and Rust, and mainly working on DevSecOps and Kubernetes.

相關文章