適用對象

把文件搬進 Markdown，不必事後整理

遷移文件通常意味著先轉換 HTML，再花更久的時間移除轉換器保留下來的東西。這種移除正是 Clean Web Clipper 的設計核心，也是經過測量的部分：在 512 個頁面上沒有任何殘留的 HTML 標籤。

轉換之後的整理工作

轉換本身只要一秒。花掉整整一週的，是隨之而來的一切：在每個檔案頂端重複的左側導覽、版本選擇器、「本頁內容」側欄、意見回饋元件、麵包屑，以及八欄頁尾。乘上兩百個頁面，一次遷移就變成一個尋找取代的專案，每個來源網站還得用一套不同的選擇器。

接著，你最需要的部分送達時卻已經受損。程式碼區塊失去語言標籤，所以沒有任何語法醒目提示，讀者也分辨不出 shell 指令和 JSON 內容。儲存格中有清單的表格崩壞了。提示框變成孤立的段落，沒有任何標記說明它們是警告。修好這些不是尋找取代的工作，而是得把每一頁重讀一遍。

沒人事先規劃的，是事後的稽核。六週後，有人問新網站上的某一段，是舊網站原本就有的，還是遷移期間寫的；如果轉換出來的檔案從未記錄它們來自哪個網址，這個問題除了去找原始頁面之外無解，而文件網站若已經關閉，就什麼也找不到。每個匯入檔案裡的一行 source 就能解決這件事，一行 date 則能說明匯入的是哪個版本。

能乾淨對應的東西

• 標題、清單、表格、程式碼區塊和註腳，全都對應到標準 Markdown。
• 程式碼區塊保留語言標籤：技術語料上 156 個保留了 73 個，比較的引擎分別是 20 個和 0 個。
• 在 512 個測量頁面上沒有任何殘留的 HTML 標籤。
• 導覽側欄、版本選擇器和「本頁內容」側欄會被刪除，而不是被轉換。
• 提示框和強調區塊變成引用區塊，因為 Markdown 沒有對應的標準語法。
• 檔名範本和子資料夾讓匯入的檔案在數量增加時仍保持有序。
• 每個檔案都帶有它來自的網址，所以審查時，匯入的段落仍能追溯到來源頁面。
• 註腳會在清理程式移除它們所依賴的元素 id 之前先收集：這個順序上的細節，決定了參考連結能不能保留下來。

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

## Workflow

Django can create migrations for you. Make changes to your models, then run:

```bash
python manage.py makemigrations
```

> **Note:** migrations are files on disk. Commit them with your code.

| Command         | What it does                              |
| --------------- | ----------------------------------------- |
| `makemigrations`| Writes new migrations from model changes  |
| `migrate`       | Applies migrations to the database        |

為遷移設定擷取

兩項設定、一個資料夾，以及一條關於提交的工作規則。提交規則正是讓之後的審查成為可能的部分。

1. 在文件儲存庫中建立 import/ 目錄，和完成後頁面要放的位置分開。遷移進行期間，原始轉換結果和編輯過的頁面絕不該放在同一個資料夾。
2. 從擴充功能圖示開啟選項，把存放位置指向 import/，並把按下圖示時的動作設為「存到資料夾」。三十個頁面就是三十次按鍵；不該同時也是三十個視窗。
3. 把檔名範本設為 {domain}-{title}。從兩三個來源網站匯入時，標題會不斷撞名，而網域能讓「Overview」不會變成 overview-3。
4. 在 frontmatter 中開啟 title、source 和 extraction。source 能回答六週後的稽核問題；extraction 則告訴你哪些頁面來自結構化資料，而不是呈現出來的內容。
5. 把圖片保留為連結，而不是略過。你不會保留這些網址，但連結就是清單：它記錄了這個頁面有一張圖表，而這正是規劃資源檔工作時需要的。
6. 擷取有分頁標籤或摺疊區塊的頁面前，先把它們打開。擴充功能轉換的是瀏覽器已經呈現的內容，而點擊才插入內容的分頁標籤，在被點擊之前並不在 DOM 裡。
7. 把原始匯入提交為一個提交，再在之後的提交中重新組織。這樣之後的每一份差異比對，顯示的都是你的編輯改動，而不是你的改動和轉換結果混在一起。

匯入的設定

這些設定是為一批會由人逐頁審查、然後編輯的檔案選的，而不是為一個讀過一次就被遺忘的資料夾。

## Installing

> **Warning:** upgrading across two major versions at once is not supported.

npm

```bash
npm install example-cli --save-dev
```

pnpm

```bash
pnpm add -D example-cli
```

兩個分頁標籤都已呈現在 DOM 中，所以都被擷取下來，一個接一個。
只有點擊後才呈現的分頁標籤就不會。

三次遷移

三十頁廠商文件

合作夥伴的 API 參考文件必須放進你們的文件裡。你把三十個頁面擷取到 import/，每頁一次按鍵。程式碼區塊帶著標籤送達：在技術語料上，語言標籤在 156 個程式碼區塊中保留了 73 個，比較的引擎分別是 20 個和 0 個；左側導覽、版本選擇器和意見回饋元件則完全沒有出現。

接下來你要編輯的是文字和結構。你不必編輯的，是單純的 HTML 轉換會在每個檔案頂端留下的兩百行側欄，而這正是遷移要花好幾週的真正原因。

以提示框建構的指南

來源指南大量使用警告、注意和提示框。Markdown 對這三種都沒有標準語法，所以三者都會變成引用區塊：內容保留，三種類型之間的區別則不保留。

這件事值得在開始之前、而不是之後知道，因為依類型重新標記是一次人工作業，工作量取決於來源。在原始匯入中找出引用區塊，就能估算這次作業的規模，而那只是一次 grep，不必逐頁閱讀。

網站關閉前的搶救

一個產品即將停止服務，它的文件在月底下線。這裡沒有爬蟲，所以只能一次一頁；但每一頁送達時，檔頭都帶著原始網址，這正是之後這次搶救還有價值的原因。

圖片是需要另外規劃的部分。它們仍是連結，指向一個即將不存在的網站，所以重要頁面的圖表必須在期限前手動儲存；匯入檔案中的連結清單，就是這件事的檢查表。

和其他轉換方式相比

一次遷移通常會同時使用其中兩種。誠實的比較，是看人工作業落在哪裡，而不是有沒有人工作業。

匯入後需要修正的地方

我的提示框現在全都長得一樣

警告、注意和提示都會變成引用區塊，因為 Markdown 沒有可以對應的標準提示框語法。文字完整，行首的強調標記通常也會保留，所以開頭是粗體「Warning:」的警告仍然會這麼寫。依類型重新標記是一次需要規劃的作業；它的規模，只要 grep 一次引用區塊就知道。

有個頁面頂端沒有標題

空的標題會被捨棄，而在許多文件網站上，看得到的頁面標題根本不是標題元素，而是文章內文之外的導覽元素。標題仍會透過取自頁面自身中繼資料的 title frontmatter 欄位進入檔案。把它提升為 H1 是一個機械式的步驟，可以用腳本套用到整批匯入。

圖片連結仍然指向舊網站

一定會的。擴充功能不下載二進位資源，所以每張圖片都是指向原本位置的連結，匯入的檔案並不自成一體。把這些連結當成清單而不是結果：它們告訴你哪些頁面有資源檔、有多少，而這正是資源檔遷移需要的清單。

有個頁面記錄了 jsonld-articlebody，讀起來和網站不一樣

那個頁面把文章文字放在結構化資料中，始終沒有完成呈現，所以內文改從結構化資料讀取。兩者不一定相同：呈現頁面比結構化資料更新得勤的網站，會在那個區塊留下較舊的版本。提交之前，這些頁面值得和原始頁面對照閱讀。

它不是什麼

它不是遷移工具：沒有爬蟲、不改寫連結、沒有重新導向對照表，也不下載資源檔。圖片仍是指向原始網站的連結，所以匯入的檔案並不自成一體。Markdown 無法表達的東西（分頁式程式碼區塊、引入片段、提示框類型、自訂元件）會被攤平成最接近的純文字形式，所以內容保留，樣式不保留。它轉換的是頁面已經呈現的內容，所以尚未展開的摺疊區塊裡的文字不在 DOM 中，也不會被擷取。

常見問題