Dành cho ai

Lưu tài liệu API thành Markdown, giữ nguyên mã

Clean Web Clipper đọc ngôn ngữ ngay trên trang: từ class của khối mã, phần tử cha hoặc mã đánh dấu riêng của trình tô màu cú pháp, rồi ghi nó vào khối mã. Trên bộ mẫu kỹ thuật chín trang, nhãn được giữ ở 73 trên 156 khối mã, so với 20 và 0 của hai công cụ trích xuất được so sánh.

Vì sao tài liệu trích xuất cần dọn dẹp

Tài liệu phần lớn là mã, và mã lại là phần mà hầu hết web clipper làm rơi. Bạn lưu một trang tài liệu framework hoặc một câu trả lời sẽ cần dùng lại, dán vào ghi chú, và mọi khối mã đều trơn: không js, không bash, không sql. Màu sắc biến mất, và cùng với nó là cách nhanh nhất để phân biệt một lệnh shell với một đoạn JSON chỉ bằng một cái liếc mắt.

Phần hư hại còn lại nằm ở cấu trúc. Một bảng có đoạn mã mẫu trong một ô bị dồn thành một dòng. Bộ chọn phiên bản và cột “trên trang này” rơi vào giữa bài viết. Lớp div bọc quanh widget mã còn sót lại dưới dạng mã đánh dấu thô. Sửa tất cả bằng tay tốn thời gian hơn cả viết ghi chú từ trí nhớ, nên phần lớn mọi người thôi trích xuất tài liệu và cứ để một thẻ mở cho tới khi nó lỗi thời.

Chính cái thẻ đó là vấn đề thứ ba. Tài liệu có phiên bản, còn URL thường thì không – trang bạn đọc cho v4 lặng lẽ thành v6, với một cờ bị đổi tên và một tùy chọn bị bỏ, còn dấu trang vẫn mở được – nhưng ra văn bản khác. Không có gì trong ghi chú của bạn cho biết bạn thực sự đã làm dựa trên phiên bản nào. Một tệp có URL và ngày của chính trang trong phần đầu trả lời được câu hỏi đó một năm sau; dấu trang thì chưa bao giờ làm được.

Những gì vào ghi chú thay vào đó

• Khối mã có nhãn. ```js, không trơn – tô màu cú pháp hoạt động trong Obsidian, VS Code và GitHub ngay khi bạn dán.
• Ngôn ngữ được đọc, không đoán. Nó lấy từ class mà trình tô màu của chính trang để lại, nên nhãn chính xác như trang nguồn.
• Bảng có mã trong ô vẫn nguyên vẹn: giữ được 12 trên 15 trong bộ mẫu kỹ thuật, so với 7 của mỗi công cụ được so sánh.
• Liên kết tham chiếu thành chú thích [^1] với phần định nghĩa ở cuối, nên trích dẫn của một bản đặc tả vẫn trỏ đúng ngay trong ghi chú.
• Thanh bên và bộ chọn phiên bản bị cắt bỏ, không bị chuyển đổi: không có thẻ HTML sót lại nào trên 512 trang đã đo.
• Việc trích xuất chạy trên DOM đã hiển thị, nên các trang tài liệu dựng bằng JavaScript được chụp đúng như bạn thấy.
• Chuỗi thảo luận Reddit giữ cấu trúc và điểm của từng bình luận – nơi có tới một nửa số câu trả lời thật về một thư viện.
• Trường extraction cho biết đã đi đường nào: dom, hoặc jsonld-articlebody khi trang gửi văn bản trong dữ liệu có cấu trúc mà không bao giờ hiển thị nó.

• 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

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

Thiết lập cho tài liệu

Mất sáu phút một lần, sau đó phím tắt lo phần còn lại. Mặc định được chỉnh cho việc đọc bài viết; tài liệu cần tên tệp khác, không có trường tác giả và không có hình ảnh.

1. Cài tiện ích và ghim biểu tượng lên thanh công cụ. Nhấp chuột phải vào biểu tượng và chọn Tùy chọn để mở phần cài đặt trong một thẻ.
2. Đặt việc cú nhấp vào biểu tượng sẽ làm là “lưu vào thư mục”. Đó là thứ biến một lần trích xuất thành một phím bấm, không có cửa sổ nào chắn đường. Cửa sổ xem trước hữu ích khi bạn đang làm quen công cụ và vướng víu sau đó.
3. Chọn thư mục. Trỏ nó vào một thư mục bạn vốn đã quản lý bằng version control, như docs/clips trong repository bạn đang làm. Trình duyệt hỏi xác nhận một lần và nhớ quyền đã cấp cho hồ sơ đó.
4. Đặt mẫu tên tệp là {domain}-{title}. Bốn framework đều có một trang tên “Getting started”, và nếu tên không có tên miền, trang thứ tư sẽ lặng lẽ thành getting-started-4.
5. Trong phần frontmatter, giữ source và extraction, tắt author. Tài liệu hiếm khi có tên người viết, và một trường trống trong mọi tệp là nhiễu mà sớm muộn bạn cũng phải xóa.
6. Đặt hình ảnh là bỏ qua. Ảnh chụp IDE của người khác không tìm kiếm được, và liên kết hình trỏ tới một CDN rồi sẽ đổi chỗ.
7. Mở chrome://extensions/shortcuts và kiểm tra Alt+Shift+M đã được gán. Nếu một tiện ích khác chiếm mất, đây là nơi bạn lấy lại.

Cài đặt hợp với lập trình viên

Đây là những giá trị đáng đổi so với mặc định, kèm lý do mỗi giá trị quan trọng riêng với tài liệu chứ không phải với việc đọc nói chung.

Run the migration before starting the server:

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

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

The second fence carried `class="language-sql"`. The first carried nothing,
and is left bare rather than tagged with a guess.

Ba phiên làm việc

Ghim đúng phiên bản bạn đã dùng

Bạn đang ở nhánh v4 của tài liệu một framework, đọc trang về một cờ cấu hình đã được đổi tên ở v5. Bạn nhấn Alt+Shift+M. Tệp được lưu thành example-dev-configuration-reference.md trong docs/clips, với source trỏ tới URL /v4/ và ngày do trang khai báo trong phần đầu.

Tám tháng sau, cờ đó hoạt động khác trên production và không ai nhớ vì sao nó được đặt như vậy. Bản trích nằm trong repository, cùng khoảng commit với thay đổi, và nó cho biết quyết định được đưa ra dựa trên phiên bản tài liệu nào. URL đang hoạt động giờ phục vụ v6 và không còn nhắc tới cờ đó nữa.

Chuỗi thảo luận trên diễn đàn đã thật sự giải quyết vấn đề

Tài liệu chính thức mô tả trường hợp suôn sẻ; cách sửa cho trường hợp của bạn nằm trong một chuỗi Reddit, sâu bốn bình luận, với câu trả lời được chấp nhận ở mức 140 điểm nằm dưới một câu trả lời sai 30 điểm. Bạn trích xuất chuỗi đó. Quy tắc theo trang web đưa nó vào threads, và cấu trúc bình luận được chuyển thành các trích dẫn khối lồng nhau, kèm điểm của từng bình luận.

Điểm số là phần quan trọng khi bạn đọc lại. Một bản sao chép phẳng của chuỗi đó mất hoàn toàn tín hiệu thứ tự, và bạn phải đọc lại năm ý kiến mà không có cách nào biết cộng đồng đồng tình với ý kiến nào.

Một bảng biến môi trường, thẳng vào pull request

Hướng dẫn triển khai có một bảng mười tám biến môi trường, ba trong số đó có đoạn mã mẫu trong ô. Bạn chọn bảng trên trang, trích xuất phần đã chọn và dán Markdown vào phần mô tả pull request. GitHub hiển thị nó thành bảng vì đó là bảng GFM, không phải ảnh chụp màn hình.

Trên bộ mẫu kỹ thuật mười lăm bảng, bộ chuyển đổi này giữ được mười hai bảng, trong khi mỗi công cụ được so sánh giữ được bảy. Những ô làm hỏng bộ chuyển đổi chung chính là những ô này – ô có mã hoặc danh sách bên trong.

So với các cách thông thường

Cách nào dưới đây cũng dùng được, và mỗi cách đều là việc ai đó trong nhóm bạn đang làm lúc này. Cột thứ ba là cái giá thật – kể cả với tiện ích này.

Khi kết quả ra không đúng

Vì sao khối mã của tôi không có nhãn?

Vì trang không cho biết đó là ngôn ngữ gì. Clean Web Clipper đọc ngôn ngữ từ class mà trình tô màu của chính trang để lại; nó không nhìn vào mã rồi đoán. Một đoạn mẫu định dạng thủ công không có class sẽ cho ra khối mã trơn, và đó là kết quả trung thực. Nhãn python đoán bừa trên một đoạn lệnh shell còn tệ hơn không có nhãn, vì khi đó phần tô màu sẽ tự tin tô sai.

Vì sao thiếu mất một nửa hướng dẫn?

Hầu như luôn là do tab hoặc accordion. Tiện ích chuyển đổi những gì trình duyệt đã thật sự hiển thị, và một tab chỉ chèn nội dung khi bạn nhấp vào sẽ không có trong DOM cho tới khi bạn nhấp. Mở tab, mở rộng mục, rồi trích xuất – hoặc trích xuất mỗi biến thể một lần. Nếu trang hiển thị mọi tab và ẩn chúng bằng CSS, tất cả sẽ được chuyển sang, lần lượt từng tab.

Vì sao nó báo không có bài viết?

Một API playground, trang kết quả tìm kiếm hay chỉ mục gói phần lớn là nhãn liên kết, và tiện ích cố ý từ chối những trang đó – nếu hơn khoảng một phần tư số ký tự trích xuất nằm trong liên kết, nó báo “không có bài viết” thay vì đưa bạn ba trăm mục. Việc từ chối đó là lý do tỷ lệ “văn bản hữu ích” của nó thấp hơn các công cụ luôn trả về một thứ gì đó.

extraction: "jsonld-articlebody" trong tệp của tôi nghĩa là gì?

Là trang đã gửi văn bản bài viết trong dữ liệu có cấu trúc nhưng không bao giờ hiển thị xong vào DOM, nên phần thân được đọc từ dữ liệu có cấu trúc. Điều này được ghi lại thay vì bị giấu đi, vì hai đường có thể cho kết quả khác nhau – bản trong dữ liệu có cấu trúc đôi khi là bản nháp cũ hơn, và đôi khi lại là phiên bản đầy đủ duy nhất. Khi thấy giá trị đó, bạn nên liếc qua bản gốc trước khi dựa vào văn bản.

Những gì nó không làm

Nó không thu thập cả một trang tài liệu – mỗi lần một trang, đúng trang bạn đang mở. Nó không tải hình ảnh, sơ đồ hay tệp nhị phân khác – liên kết hình vẫn trỏ tới trang gốc. Nó không đoán ngôn ngữ cho khối mã không có nhãn, nên trang mà trình tô màu không để lại class nào sẽ cho ra khối mã trơn chứ không phải khối mã gắn sai nhãn. Và trên trang không có phần thân bài viết – một API playground, một trang kết quả tìm kiếm – nó báo “không có bài viết” thay vì đưa bạn ba trăm liên kết.

Câu hỏi