Dành cho ai

Chuyển tài liệu sang Markdown mà không phải dọn dẹp

Chuyển đổi tài liệu thường nghĩa là chuyển HTML rồi mất thời gian hơn để gỡ những gì bộ chuyển đổi giữ lại. Việc gỡ bỏ đó là thứ Clean Web Clipper được xây dựng xoay quanh, và là phần đã được đo: không có thẻ HTML sót lại trên 512 trang.

Việc dọn dẹp sau khi chuyển đổi

Bản thân việc chuyển đổi mất một giây. Thứ tốn cả tuần là mọi thứ đi kèm – thanh điều hướng bên trái lặp lại ở đầu mỗi tệp, bộ chọn phiên bản, cột “trên trang này”, widget góp ý, breadcrumb và tám cột chân trang. Nhân với hai trăm trang, một đợt di chuyển tài liệu biến thành dự án tìm-và-thay với bộ selector khác nhau cho mỗi trang nguồn.

Rồi những phần bạn cần nhất lại tới nơi trong tình trạng hư hại. Khối mã mất ngôn ngữ, nên không có gì được tô màu và người đọc không phân biệt được lệnh shell với một đoạn JSON. Bảng có danh sách trong ô bị vỡ. Khung cảnh báo thành những đoạn văn mồ côi, không có gì đánh dấu chúng là cảnh báo. Sửa những thứ đó không phải việc tìm-và-thay; đó là đọc lại từng trang.

Phần không ai lên kế hoạch là khâu kiểm tra sau đó. Sáu tuần sau, ai đó hỏi một đoạn trong trang mới vốn có ở trang cũ hay được viết trong lúc di chuyển, và nếu các tệp đã chuyển đổi chưa bao giờ mang địa chỉ nguồn, câu hỏi đó không có câu trả lời trừ khi tìm lại trang gốc – mà với một trang tài liệu đã bị tắt thì nghĩa là không tìm được gì. Một dòng source trong mỗi tệp nhập vào chỉ tốn một dòng và giải quyết điều đó, còn một dòng date cho biết phiên bản nào đã được nhập.

Những gì được chuyển sang gọn gàng

• Tiêu đề mục, danh sách, bảng, khối mã và chú thích đều chuyển sang Markdown chuẩn.
• Khối mã giữ nhãn ngôn ngữ: giữ được 73 trên 156 trong bộ mẫu kỹ thuật, so với 20 và 0 của các công cụ được so sánh.
• Không có thẻ HTML sót lại trên 512 trang đã đo.
• Thanh điều hướng bên, bộ chọn phiên bản và cột “trên trang này” bị cắt bỏ, không bị chuyển đổi.
• Khung cảnh báo và khung ghi chú thành trích dẫn khối, vì Markdown không có cú pháp chuẩn cho chúng.
• Mẫu tên tệp và thư mục con giữ cho bộ tệp nhập vào gọn gàng khi nó lớn dần.
• Mọi tệp đều mang địa chỉ nguồn, nên một đoạn văn đã nhập vẫn truy được về trang gốc trong lúc rà soát.
• Chú thích được gom trước khi bộ lọc xóa các id phần tử mà chúng phụ thuộc – một chi tiết về thứ tự quyết định liên kết tham chiếu có còn tồn tại hay không.

• Các con số này lấy từ đâu: trang phép đo, kèm phiên bản công cụ và ngày đo

## 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        |

Thiết lập cho một đợt di chuyển

Hai cài đặt, một thư mục và một quy tắc làm việc về commit. Quy tắc commit là phần giúp việc rà soát về sau khả thi.

1. Tạo thư mục import/ trong repository tài liệu, tách khỏi nơi các trang hoàn chỉnh sẽ nằm. Bản chuyển đổi thô và trang đã biên tập không bao giờ nên nằm chung một thư mục trong lúc di chuyển.
2. Mở Tùy chọn từ biểu tượng tiện ích, trỏ nơi lưu vào import/, và đặt việc cú nhấp vào biểu tượng sẽ làm là “lưu vào thư mục”. Ba mươi trang là ba mươi phím bấm; không nên thêm ba mươi cửa sổ.
3. Đặt mẫu tên tệp là {domain}-{title}. Một đợt nhập lấy từ hai ba trang nguồn liên tục trùng tiêu đề, và tên miền là thứ giữ cho “Overview” không thành overview-3.
4. Bật title, source và extraction trong frontmatter. source là thứ trả lời câu hỏi kiểm tra sáu tuần sau; extraction cho biết trang nào lấy từ dữ liệu có cấu trúc chứ không phải từ những gì đã hiển thị.
5. Giữ hình ảnh dưới dạng liên kết thay vì bỏ qua. Bạn sẽ không giữ những URL đó, nhưng liên kết chính là bảng kiểm kê – nó ghi lại rằng trang có sơ đồ, đúng thứ bạn cần khi lên kế hoạch xử lý tài nguyên.
6. Trước khi trích xuất trang có tab hoặc accordion, hãy mở chúng. Tiện ích chuyển đổi những gì trình duyệt đã hiển thị, và một tab chỉ chèn nội dung khi nhấp sẽ không có trong DOM cho tới khi được nhấp.
7. Commit bản nhập thô thành một commit, rồi tái cấu trúc trong các commit sau đó. Như vậy mọi diff về sau đều cho thấy thay đổi biên tập của bạn chứ không phải hỗn hợp giữa thay đổi của bạn và của việc chuyển đổi.

Cài đặt cho một đợt nhập

Các giá trị này được chọn cho một bộ tệp sẽ được một người rà soát, từng trang một, rồi biên tập – không phải cho một thư mục đọc một lần rồi quên.

## 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
```

Both tabs were rendered in the DOM, so both came across, one after the other.
A tab that renders only when clicked would not have.

Ba đợt di chuyển

Ba mươi trang tài liệu của nhà cung cấp

Tài liệu tham chiếu API của một đối tác phải nằm trong bộ tài liệu của bạn. Bạn trích xuất ba mươi trang vào import/, mỗi trang một phím bấm. Khối mã tới nơi có nhãn: trên bộ mẫu kỹ thuật, nhãn ngôn ngữ được giữ ở 73 trên 156 khối mã so với 20 và 0 của các công cụ được so sánh, còn thanh điều hướng bên trái, bộ chọn phiên bản và widget góp ý thì không tới đâu cả.

Thứ bạn biên tập sau đó là văn xuôi và cấu trúc. Thứ bạn không phải biên tập là hai trăm dòng thanh bên mỗi trang mà một lần chuyển HTML thẳng sẽ đổ vào đầu mỗi tệp – lý do thật khiến các đợt di chuyển kéo dài hàng tuần.

Một hướng dẫn dựng từ các khung cảnh báo

Hướng dẫn nguồn dùng rất nhiều khung warning, note và tip. Markdown không có cú pháp chuẩn cho loại nào, nên cả ba đều thành trích dẫn khối – nội dung còn, sự phân biệt giữa ba loại thì không.

Điều đó đáng biết trước khi bắt đầu chứ không phải sau, vì gắn lại nhãn theo loại là một lượt làm thủ công và khối lượng của nó tùy vào nguồn. Tìm các trích dẫn khối trong bản nhập thô là cách ước lượng lượt đó, và chỉ cần một lệnh grep thay vì đọc từng trang.

Cứu tài liệu trước khi một trang bị tắt

Một sản phẩm sắp ngừng và tài liệu của nó sẽ ngoại tuyến vào cuối tháng. Ở đây không có trình thu thập, nên phải làm từng trang một – nhưng mỗi trang tới nơi thành một tệp có địa chỉ gốc trong phần đầu, và chính điều đó khiến việc cứu tài liệu có giá trị về sau.

Hình ảnh là phần cần lên kế hoạch riêng. Chúng vẫn là liên kết tới một trang sắp không còn tồn tại, nên những trang quan trọng cần lưu sơ đồ bằng tay trước hạn; bảng kiểm kê liên kết trong các tệp đã nhập chính là danh sách kiểm tra cho việc đó.

So với các cách chuyển đổi khác

Một đợt di chuyển thường dùng hai trong số này cùng lúc. So sánh trung thực là về chỗ công việc thủ công rơi vào, chứ không phải có hay không có.

Những gì cần sửa sau một đợt nhập

Mọi khung ghi chú giờ trông giống hệt nhau

Warning, note và tip đều thành trích dẫn khối, vì Markdown không có cú pháp khung cảnh báo chuẩn để ánh xạ. Văn bản còn nguyên và dấu nhấn ở đầu dòng thường vẫn còn, nên một cảnh báo bắt đầu bằng “Warning:” in đậm vẫn nói như vậy. Gắn lại nhãn theo loại là một lượt bạn lên kế hoạch; khối lượng của lượt đó chỉ cách một lệnh grep tìm trích dẫn khối.

Một trang tới nơi mà không có tiêu đề ở đầu

Tiêu đề trống bị bỏ, và trên nhiều trang tài liệu, tiêu đề trang nhìn thấy được hoàn toàn không phải tiêu đề mục mà là một phần tử điều hướng nằm ngoài phần thân bài viết. Tiêu đề vẫn vào tệp qua trường frontmatter title, lấy từ siêu dữ liệu của chính trang. Nâng nó thành H1 là một bước máy móc bạn có thể viết script cho cả bộ tệp nhập.

Liên kết hình vẫn trỏ tới trang cũ

Chúng sẽ như vậy. Tiện ích không tải tệp nhị phân nào, nên mọi hình ảnh là liên kết tới chỗ cũ, và bộ tệp nhập vào không tự đủ. Hãy coi các liên kết là bảng kiểm kê chứ không phải kết quả – chúng cho biết trang nào có tài nguyên và bao nhiêu, đúng danh sách mà việc di chuyển tài nguyên cần.

Một trang ghi jsonld-articlebody và đọc khác với trang web

Trang đó gửi văn bản bài viết trong dữ liệu có cấu trúc mà không bao giờ hiển thị xong, nên phần thân lấy từ dữ liệu có cấu trúc. Hai thứ không phải lúc nào cũng giống nhau – một trang cập nhật phần hiển thị thường xuyên hơn dữ liệu có cấu trúc sẽ để lại phiên bản cũ hơn trong khối đó. Đó là những trang cần đọc đối chiếu với bản gốc trước khi commit.

Nó không phải là gì

Nó không phải công cụ di chuyển tài liệu: không trình thu thập, không viết lại liên kết, không bản đồ chuyển hướng, không tải tài nguyên. Hình ảnh vẫn là liên kết tới trang gốc, nên bộ tệp nhập vào không tự đủ. Mọi thứ Markdown không biểu diễn được (khối mã chia tab, include, loại khung cảnh báo, thành phần tùy chỉnh) được trải phẳng về dạng thuần gần nhất, nên nội dung còn nhưng kiểu dáng thì không. Và nó chuyển đổi những gì trang đã hiển thị, nên văn bản trong một accordion chưa mở không có trong DOM và không được trích xuất.

Câu hỏi