適用對象

把 API 文件存成 Markdown，程式碼完整保留

Clean Web Clipper 從頁面上讀取語言：來自程式碼區塊的 class、父元素，或語法醒目提示工具自己的標記，並把它寫進程式碼區塊。在一份九個頁面的技術語料上，語言標籤在 156 個程式碼區塊中保留了 73 個，比較的兩個引擎分別是 20 個和 0 個。

為什麼擷取下來的文件還得整理

文件大部分是程式碼，而程式碼正是多數擷取工具會弄丟的部分。你把一頁框架文件或一個之後還會用到的答案存下來，貼進筆記，結果每個程式碼區塊都沒有標籤：沒有 js、沒有 bash、沒有 sql。顏色不見了，一眼分辨 shell 指令和 JSON 內容的最快方法也跟著不見。

其餘的損害是結構上的。儲存格裡有程式碼範例的表格，會擠成一行。版本選擇器和「本頁內容」側欄跑到文章中間。程式碼元件外層的 div 包裝以原始標記的形式留下來。手動修好這些，比憑記憶重寫筆記還花時間，所以大多數人乾脆不再擷取文件，只是讓分頁一直開著，直到內容過時。

分頁本身就是第三個問題。文件有版本，網址通常沒有：你為 v4 讀的頁面悄悄變成 v6，旗標改了名、選項被移除，書籤卻仍然打得開，只是內容已經不同。你的筆記裡沒有任何東西記錄你實際依據的是哪個版本。檔頭帶有網址和頁面自身日期的檔案，一年後還能回答這個問題；書籤從來做不到。

筆記裡改為留下什麼

• 程式碼區塊帶有標籤。 是 ```js，不是空白的區塊：貼上的那一刻，Obsidian、VS Code 和 GitHub 就能醒目提示語法。
• 語言是讀出來的，不是猜的。 它來自網站自己的語法醒目提示工具留下的 class，所以標籤和來源頁面一樣正確。
• 儲存格中有程式碼的表格保持完整：技術語料上保留了 15 個中的 12 個，比較的引擎各保留 7 個。
• 參考連結變成 [^1] 註腳，定義放在結尾，所以規格文件中的引用在筆記裡依然有效。
• 側欄和版本選擇器會被刪除，而不是被轉換：在 512 個測量頁面上沒有任何殘留的 HTML 標籤。
• 擷取在呈現後的 DOM 上執行，所以用 JavaScript 建置的文件網站，會照你看到的樣子擷取下來。
• Reddit 討論串保留結構和每則留言的分數，而關於一個函式庫的真正解答，有一大半就在那裡。
• extraction 欄位說明走的是哪條路徑：dom，或是頁面把文字放在結構化資料中、始終沒有呈現時的 jsonld-articlebody。

• 這些數字從哪裡來：實測數據頁面，附引擎版本與日期

The JSON API returns some data that looks like this:

```js
[
  { category: "Fruits", price: "$1", stocked: true, name: "Apple" },
  { category: "Vegetables", price: "$2", stocked: true, name: "Spinach" }
]
```

## Step 1: Break the UI into a component hierarchy

為文件設定擷取

花六分鐘設定一次，之後快速鍵會處理其餘的事。預設值是為閱讀文章調整的；文件需要不同的檔名、不需要作者欄位，也不需要圖片。

1. 安裝擴充功能並把圖示釘選到工具列。在圖示上按右鍵，選擇選項，在分頁中開啟設定。
2. 把按下圖示時的動作設為「存到資料夾」。這樣一次擷取就只是一個按鍵，沒有視窗擋路。預覽視窗在你熟悉工具時很有用，之後就只會礙事。
3. 選擇資料夾。指向你已經納入版本控制的目錄，例如你正在開發的儲存庫中的 docs/clips。瀏覽器會詢問確認一次，並記住該設定檔的授權。
4. 把檔名範本設為 {domain}-{title}。四個框架都有一頁叫「Getting started」，檔名裡沒有網域的話，第四個就會悄悄變成 getting-started-4。
5. 在 frontmatter 區段保留 source 和 extraction，關閉 author。文件很少署名，每個檔案裡都有一個空欄位只是雜訊，最後你還得把它刪掉。
6. 把圖片設為略過。別人 IDE 的螢幕截圖無法搜尋，而圖片連結指向的 CDN 遲早會搬家。
7. 開啟 chrome://extensions/shortcuts，確認 Alt+Shift+M 已經綁定。如果被其他擴充功能占用，就在這裡搶回來。

適合開發者的設定

這些是值得從預設值改掉的設定，以及每一項為什麼特別對文件重要，而不只是對一般閱讀重要。

Run the migration before starting the server:

```
./bin/migrate --env production
```

```sql
SELECT id, created_at FROM sessions WHERE expires_at < now();
```

第二個區塊帶有 `class="language-sql"`。第一個什麼都沒有，
所以保持沒有標籤，而不是標上猜測的語言。

三段實際工作

鎖定你實際依據的版本

你在看某個框架 v4 分支的文件，讀到一個在 v5 被改名的設定旗標。你按下 Alt+Shift+M。檔案以 example-dev-configuration-reference.md 存進 docs/clips，source 指向 /v4/ 網址，檔頭帶有頁面宣告的日期。

八個月後，這個旗標在正式環境中的行為變了，沒有人記得當初為什麼這樣設定。擷取內容就在儲存庫裡，和那次變更位於同一段提交範圍內，它說明了這個決定是依據哪個版本的文件做的。線上網址現在提供的是 v6，已經完全沒提到這個旗標。

真正解決問題的論壇討論串

官方文件描述的是理想情況；你的狀況的解法在一個 Reddit 討論串裡，往下四層留言，被採納的答案有 140 分，排在一個只有 30 分的錯誤答案下面。你擷取這個討論串。個別網站規則把它送進 threads，留言結構以巢狀引用區塊呈現，每則都附上分數。

回頭再讀時，分數才是重點。直接複製貼上的扁平版本會完全失去排序訊號，你只能重讀五種意見，卻無從得知社群認同哪一個。

一張變數表格，直接放進 pull request

部署指南裡有一張包含十八個環境變數的表格，其中三個儲存格含有程式碼範例。你在頁面上選取表格，擷取選取範圍，把 Markdown 貼進 pull request 說明。GitHub 會把它顯示為表格，因為它是 GFM 表格，不是螢幕截圖。

在包含十五個表格的技術語料上，這個序列化程式保留了十二個表格，比較的引擎各保留七個。會讓通用轉換器出錯的，正是這種儲存格：裡面有程式碼或清單的儲存格。

和常見做法相比

以下每一種都行得通，而且每一種都是你團隊裡有人正在用的方法。第三欄是誠實的代價，包括這個擴充功能在內。

結果不對的時候

為什麼我的程式碼區塊沒有標籤？

因為頁面沒有說明它是什麼語言。Clean Web Clipper 從網站自己的語法醒目提示工具留下的 class 讀取語言；它不會看程式碼來猜。沒有 class、手動排版的範例會產生沒有標籤的區塊，這是誠實的結果。在 shell 片段上猜錯成 python 標籤比沒有標籤更糟，因為醒目提示會信心滿滿地把錯的東西上色。

為什麼指南少了一半？

幾乎都是分頁標籤或摺疊區塊造成的。擴充功能轉換的是瀏覽器實際呈現的內容，而點擊後才插入內容的分頁標籤，在你點擊之前並不在 DOM 裡。先打開分頁標籤、展開區段，再擷取；或者每個版本各擷取一次。如果網站會呈現所有分頁標籤、只用 CSS 隱藏，它們全都會依序被擷取下來。

為什麼它說沒有文章？

API 測試介面、搜尋結果頁或套件索引大多是連結文字，擴充功能會刻意拒絕這類頁面：如果擷取出的字元有超過約四分之一位於連結中，它會回報「沒有文章」，而不是交給你三百個項目。這種拒絕，也是它的「有用文字」得分低於那些總會傳回點什麼的引擎的原因。

我的檔案裡 extraction: "jsonld-articlebody" 是什麼意思？

代表頁面把文章文字放在結構化資料中，卻始終沒有把它呈現到 DOM 裡，所以內文改從結構化資料讀取。它會被記錄下來而不是隱藏，因為兩條路徑的內容可能不同：結構化資料中的副本有時是較早的草稿，有時卻是唯一完整的版本。看到這個值時，在依賴這段文字之前，值得先看一眼原始頁面。

它不做的事

它不會爬取文件網站：一次一頁，就是你正在看的那一頁。它不會下載圖片、圖表或其他二進位資源：圖片連結仍然指向原始網站。它不會替沒有標籤的程式碼區塊猜測語言，所以語法醒目提示工具沒有留下 class 的頁面，會產生沒有標籤的區塊，而不是標錯的區塊。在沒有文章內文的頁面上，例如 API 測試介面或搜尋結果頁，它會回報「沒有文章」，而不是交給你三百個連結。

常見問題