Turndown: Một Trình Chuyển Đổi HTML sang Markdown Viết Bằng JavaScript

Turndown

Chuyển đổi HTML thành Markdown bằng JavaScript.

Cài Đặt

npm:

npm install turndown

Trình duyệt:

<script src="https://unpkg.com/turndown/dist/turndown.js"></script>

Đối với việc sử dụng với RequireJS, các phiên bản UMD nằm trong lib/turndown.umd.js (cho Node.js) và lib/turndown.browser.umd.js cho việc sử dụng trình duyệt. Các tệp này được tạo ra khi gói npm được xuất bản. Để tạo chúng thủ công, sao chép kho này và chạy npm run build.

Sử Dụng

// For Node.js
var TurndownService = require('turndown')

var turndownService = new TurndownService()
var markdown = turndownService.turndown('<h1>Hello world!</h1>')

Turndown cũng chấp nhận các nút DOM làm đầu vào (cả các nút phần tử, nút tài liệu hoặc nút đoạn tài liệu):

var markdown = turndownService.turndown(document.getElementById('content'))

Tùy Chọn

Các tùy chọn có thể được truyền vào bằng cách sử dụng hàm khởi tạo. Ví dụ:

var turndownService = new TurndownService({ option: 'value' })

Tùy Chọn Nâng Cao

Phương Thức

addRule(key, rule)

Tham số key là tên duy nhất cho quy tắc để tham khảo dễ dàng. Ví dụ:

turndownService.addRule('strikethrough', {
  filter: ['del', 's', 'strike'],
  replacement: function (content) {
    return '~' + content + '~'
  }
})

addRule trả về thể hiện TurndownService để có thể chuỗi hóa.

Xem Mở Rộng với Quy Tắc dưới đây.

keep(filter)

Xác định các phần tử nào sẽ được giữ lại và được hiển thị dưới dạng HTML. Mặc định, Turndown không giữ lại bất kỳ phần tử nào. Tham số bộ lọc hoạt động giống như một bộ lọc quy tắc (xem phần về bộ lọc bên dưới). Ví dụ:

turndownService.keep(['del', 'ins'])
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello <del>world</del><ins>World</ins>'

Điều này sẽ hiển thị các phần tử <del> và <ins> dưới dạng HTML khi chuyển đổi.

keep có thể được gọi nhiều lần, với các bộ lọc keep được thêm mới có ưu tiên hơn các bộ lọc keep cũ. Bộ lọc keep sẽ bị ghi đè bởi các quy tắc CommonMark tiêu chuẩn và bất kỳ quy tắc được thêm mới nào. Để giữ lại các phần tử thông thường được xử lý bởi các quy tắc đó, hãy thêm một quy tắc với hành vi mong muốn.

keep trả về thể hiện TurndownService để có thể chuỗi hóa.

remove(filter)

Xác định các phần tử nào sẽ được loại bỏ hoàn toàn, tức là chuyển đổi thành một chuỗi rỗng. Mặc định, Turndown không loại bỏ bất kỳ phần tử nào. Tham số bộ lọc hoạt động giống như một bộ lọc quy tắc (xem phần về bộ lọc bên dưới). Ví dụ:

turndownService.remove('del')
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello World'

Điều này sẽ loại bỏ các phần tử <del> (và nội dung của chúng).

remove có thể được gọi nhiều lần, với các bộ lọc remove được thêm mới có ưu tiên hơn các bộ lọc remove cũ. Bộ lọc remove sẽ bị ghi đè bởi các bộ lọc keep, các quy tắc CommonMark tiêu chuẩn và bất kỳ quy tắc được thêm mới nào. Để loại bỏ các phần tử thông thường được xử lý bởi các quy tắc đó, hãy thêm một quy tắc với hành vi mong muốn.

remove trả về thể hiện TurndownService để có thể chuỗi hóa.

use(plugin|array)

Sử dụng một plugin hoặc một mảng các plugin. Ví dụ:

// Import plugins from turndown-plugin-gfm
var turndownPluginGfm = require('turndown-plugin-gfm')
var gfm = turndownPluginGfm.gfm
var tables = turndownPluginGfm.tables
var strikethrough = turndownPluginGfm.strikethrough

// Use the gfm plugin
turndownService.use(gfm)

// Use the table and strikethrough plugins only
turndownService.use([tables, strikethrough])

use trả về thể hiện TurndownService để có thể chuỗi hóa.

Xem Plugins bên dưới.

Mở Rộng với Quy Tắc

Turndown có thể được mở rộng bằng cách thêm quy tắc. Một quy tắc là một đối tượng JavaScript thuần túy với các thuộc tính filter và replacement. Ví dụ, quy tắc chuyển đổi các phần tử <p> có dạng như sau:

{
  filter: 'p',
  replacement: function (content) {
    return '\n\n' + content + '\n\n'
  }
}

Bộ lọc chọn các phần tử <p>, và hàm thay thế trả về nội dung của <p> được tách ra bằng hai dòng mới.

filter Chuỗi|Mảng|Hàm

Thuộc tính bộ lọc xác định liệu một phần tử có nên được thay thế bằng replacement của quy tắc hay không. Các nút DOM có thể được chọn dễ dàng bằng cách sử dụng tên thẻ hoặc một mảng tên thẻ:

• filter: 'p' sẽ chọn các phần tử <p>
• filter: ['em', 'i'] sẽ chọn các phần tử <em> hoặc <i>

Tên thẻ trong thuộc tính filter được mong đợi là viết thường, bất kể hình thức của chúng trong tài liệu.

Hoặc, bộ lọc có thể là một hàm trả về một giá trị boolean tùy thuộc vào việc một nút cụ thể có nên được thay thế hay không. Hàm nhận vào một nút DOM cùng với các tùy chọn của TurndownService. Ví dụ, quy tắc sau đây chọn các phần tử <a> (có href) khi tùy chọn linkStyle là inlined:

filter: function (node, options) {
  return (
    options.linkStyle === 'inlined' &&
    node.nodeName === 'A' &&
    node.getAttribute('href')
  )
}

replacement Hàm

Hàm thay thế xác định cách chuyển đổi một phần tử. Nó nên trả về chuỗi Markdown cho một nút cụ thể. Hàm nhận vào nội dung của nút, nút đó và các tùy chọn của TurndownService.

Quy tắc sau đây cho thấy cách chuyển đổi các phần tử <em>:

rules.emphasis = {
  filter: ['em', 'i'],

  replacement: function (content, node, options) {
    return options.emDelimiter + content + options.emDelimiter
  }
}

Quy Tắc Đặc Biệt

Quy tắc trống xác định cách xử lý các phần tử trống. Nó ghi đè lên mọi quy tắc (kể cả những quy tắc được thêm bằng cách sử dụng addRule). Một nút trống nếu nó chỉ chứa khoảng trắng và không phải là một phần tử <a>, <td>,<th> hoặc một phần tử void. Hành vi của nó có thể được tùy chỉnh bằng cách sử dụng tùy chọn blankReplacement.

Quy tắc giữ nguyên xác định cách xử lý các phần tử không nên được chuyển đổi, tức là hiển thị dưới dạng HTML trong đầu ra Markdown. Theo mặc định, không có phần tử nào được giữ nguyên. Các phần tử cấp độ khối sẽ được phân tách khỏi nội dung xung quanh bằng các dòng trống. Hành vi này có thể được tùy chỉnh bằng cách sử dụng tùy chọn keepReplacement.

Quy tắc loại bỏ xác định các phần tử nên loại bỏ hoàn toàn. Theo mặc định, không có phần tử nào bị loại bỏ.

Quy tắc mặc định xử lý các nút không được nhận diện bởi bất kỳ quy tắc nào khác. Theo mặc định, nó xuất nội dung văn bản của nút (cách nhau bởi dòng trống nếu nó là một phần tử cấp độ khối). Hành vi này có thể được tùy chỉnh bằng tùy chọn defaultReplacement.

Ưu tiên Quy tắc

Turndown lặp qua tập hợp các quy tắc và chọn quy tắc đầu tiên phù hợp với bộ lọc (filter). Danh sách sau đây mô tả thứ tự ưu tiên:

. Quy tắc trống
. Quy tắc được thêm (tùy chọn)
. Quy tắc Commonmark
. Quy tắc giữ nguyên
. Quy tắc loại bỏ
. Quy tắc mặc định

Tiện ích mở rộng (Plugins)

API của tiện ích mở rộng cung cấp một cách tiện lợi cho các nhà phát triển áp dụng nhiều tiện ích mở rộng. Một tiện ích mở rộng chỉ là một hàm được gọi với thể hiện TurndownService.

Thoát Ký tự Markdown

Turndown sử dụng dấu gạch chéo (\) để thoát ký tự Markdown trong đầu vào HTML. Điều này đảm bảo rằng những ký tự này không được hiểu là Markdown khi đầu ra được biên soạn lại thành HTML. Ví dụ, nội dung của <h1>1. Xin chào thế giới</h1> cần phải được thoát thành 1\. Xin chào thế giới, nếu không, nó sẽ được hiểu là một mục danh sách thay vì một tiêu đề.

Để tránh sự phức tạp và tác động đến hiệu suất khi phân tích nội dung của mọi phần tử HTML dưới dạng Markdown, Turndown sử dụng một nhóm biểu thức chính quy để thoát khỏi cú pháp Markdown tiềm năng. Do đó, các quy tắc thoát này có thể khá mạnh.

Ghi đè TurndownService.prototype.escape

Nếu bạn tự tin làm như vậy, bạn có thể muốn tùy chỉnh hành vi thoát để phù hợp với nhu cầu của bạn. Điều này có thể được thực hiện bằng cách ghi đè TurndownService.prototype.escape. escape lấy văn bản của mỗi phần tử HTML và nên trả về phiên bản với các ký tự Markdown đã được thoát.

Ghi chú: văn bản trong các phần tử mã không bao giờ được chuyển đến escape.

Cập nhật Dự án

• to-markdown đã được đổi tên thành Turndown. Xem migration guide để biết chi tiết.
• Thay đổi URL kho lưu trữ Turndown thành https://github.com/mixmark-io/turndown.

Chi tiết Tải về:

Tác giả: mixmark-io
Mã nguồn: https://github.com/mixmark-io/turndown
Giấy phép: MIT license