Remark
remark là một công cụ biến đổi markdown bằng các tiện ích. Những tiện ích này có thể kiểm tra và thay đổi đánh dấu của bạn. Bạn có thể sử dụng remark trên máy chủ, máy khách, giao diện dòng lệnh, deno, v.v.
Điểm nổi bật của tính năng
- popular (trình phân tích markdown phổ biến nhất thế giới)
- compliant (100% về CommonMark, 100% về GFM với một tiện ích)
- plugins (hơn 150 tiện ích bạn có thể lựa chọn)
- ASTs (kiểm tra và thay đổi nội dung dễ dàng)
Giới thiệu
remark là một hệ sinh thái tiện ích phổ biến rất hoạt động với markdown như dữ liệu có cấu trúc, cụ thể là cây cú pháp trừu tượng (ASTs). ASTs giúp cho các chương trình dễ dàng xử lý markdown. Chúng tôi gọi những chương trình đó là các tiện ích. Các tiện ích kiểm tra và thay đổi cây. Bạn có thể sử dụng nhiều tiện ích hiện có hoặc bạn có thể tự tạo ra tiện ích của riêng bạn.
- để tìm hiểu về markdown, xem cheatsheet and tutorial
- để biết thêm về chúng tôi, xem unifiedjs.com
- để cập nhật thông tin, xem Twitter
- để đặt câu hỏi, xem support
- để hỗ trợ, xem contribute hoặc sponsor bên dưới
Điều này là gì?
Với dự án này và một tiện ích, bạn có thể biến đổi markdown sau:
# Hello, *Mercury*!
…thành HTML sau đây:
<h1>Hello, <em>Mercury</em>!</h1>
Hiển thị mã ví dụ
Với một tiện ích khác, bạn có thể biến đổi markdown sau:
# Hi, Saturn!
…thành markdown sau đây:
## Hi, Saturn!
Hiển thị mã ví dụ
Bạn có thể sử dụng remark cho nhiều mục đích khác nhau. unified là dự án chính biến đổi nội dung với ASTs. remark thêm khả năng hỗ trợ markdown cho unified. mdast là AST markdown mà remark sử dụng.
Kho GitHub này là một monorepo chứa các gói sau đây:
- remark-parse — tiện ích để chuyển đổi markdown thành cây cú pháp (mdast)
- remark-stringify — tiện ích để lấy cây cú pháp (mdast) và chuyển đổi thành markdown đầu ra
- remark — unified,
remark-parse, vàremark-stringify, hữu ích khi đầu vào và đầu ra là markdown - remark-cli — CLI xung quanh
remarkđể kiểm tra và định dạng markdown trong các kịch bản
Khi nào tôi nên sử dụng điều này?
Nếu bạn chỉ muốn chuyển đổi markdown thành HTML (có thể có một số phần mở rộng), chúng tôi khuyến nghị sử dụng micromark thay vì vậy. remark cũng có thể làm điều đó nhưng tập trung vào ASTs và cung cấp một giao diện cho các tiện ích biến đổi chúng.
Tùy theo đầu vào bạn có và đầu ra bạn muốn, bạn có thể sử dụng các phần khác nhau của remark. Nếu đầu vào là markdown, bạn có thể sử dụng remark-parse với unified. Nếu đầu ra là markdown, bạn có thể sử dụng remark-stringify với unified. Nếu cả đầu vào và đầu ra đều là markdown, bạn có thể sử dụng remark một mình. Khi bạn muốn kiểm tra và định dạng các tệp markdown trong một dự án, bạn có thể sử dụng remark-cli.
Tiện ích
Các tiện ích của remark làm việc với markdown. Một số ví dụ phổ biến là:
- remark-gfm — thêm hỗ trợ cho GFM (markdown có định dạng của GitHub)
- remark-lint — kiểm tra markdown và cảnh báo về sự không nhất quán
- remark-toc — tạo bảng mục lục
- remark-html — chuyển đổi cây cú pháp thành HTML đã được chuỗi hóa
Những tiện ích này là gương mẫu vì những gì chúng làm và cách chúng làm khá khác nhau, tương ứng để mở rộng cú pháp markdown, kiểm tra cây, thay đổi cây và định nghĩa các định dạng đầu ra khác nhau.
Bạn có thể lựa chọn từ hơn 150 tiện ích đã tồn tại. Dưới đây là ba cách tốt để tìm các tiện ích:
- awesome-remark — sự lựa chọn của những dự án tuyệt vời nhất
- List of plugins — danh sách tất cả các tiện ích
- remark-plugin topic — bất kỳ kho lưu trữ nào được gắn thẻ trên GitHub
Một số tiện ích được chúng tôi duy trì tại tổ chức @remarkjs trong khi những tiện ích khác được duy trì bởi những người khác. Bất kỳ ai cũng có thể tạo ra các tiện ích remark, vì vậy như luôn luôn khi quyết định có nên bao gồm các phụ thuộc trong dự án của bạn, hãy đảm bảo kiểm tra cẩn thận chất lượng của các tiện ích remark nữa.
Ví dụ
Ví dụ: chuyển đổi markdown thành HTML
remark là một hệ sinh thái xung quanh markdown. Một hệ sinh thái khác dành cho HTML: rehype. Ví dụ sau đây chuyển đổi markdown thành HTML bằng cách kết hợp cả hai hệ sinh thái với remark-rehype:
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeSanitize)
.use(rehypeStringify)
.process('# Hello, Neptune!')
console.log(String(file))
}
Cho ra kết quả:
<h1>Hello, Neptune!</h1>
Ví dụ: hỗ trợ GFM và frontmatter
remark hỗ trợ CommonMark theo mặc định. Các phần mở rộng markdown không chuẩn có thể được kích hoạt bằng các tiện ích. Ví dụ sau đây thêm hỗ trợ cho GFM (autolink literals, chú thích chân trang, gạch ngang, bảng, danh sách công việc) và frontmatter (YAML):
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkFrontmatter from 'remark-frontmatter'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkFrontmatter)
.use(remarkGfm)
.use(remarkRehype)
.use(rehypeStringify)
.process('---\nlayout: home\n---\n\n# Hi ~~Mars~~Venus!')
console.log(String(file))
}
Cho ra kết quả:
<h1>Hi <del>Mars</del>Venus!</h1>
Ví dụ: kiểm tra markdown
Ví dụ sau đây kiểm tra xem phong cách mã markdown có nhất quán và tuân theo các thực hành tốt được đề xuất hay không:
import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
main()
async function main() {
const file = await remark()
.use(remarkPresetLintConsistent)
.use(remarkPresetLintRecommended)
.process('1) Hello, _Jupiter_ and *Neptune*!')
console.error(reporter(file))
}
Cho ra kết quả:
1:1 warning Missing newline character at end of file final-newline remark-lint
1:1-1:35 warning Marker style should be `.` ordered-list-marker-style remark-lint
1:4 warning Incorrect list-item indent: add 1 space list-item-indent remark-lint
1:25-1:34 warning Emphasis should use `_` as a marker emphasis-marker remark-lint
⚠ 4 warnings
Ví dụ: kiểm tra và định dạng markdown trên dòng lệnh
Ví dụ sau đây kiểm tra và định dạng markdown bằng remark-cli, đây là giao diện dòng lệnh (CLI) của remark mà bạn có thể sử dụng trong terminal của bạn. Ví dụ này giả định bạn đang ở trong một gói Node.js.
Đầu tiên, cài đặt CLI và các tiện ích:
npm install remark-cli remark-toc remark-preset-lint-consistent remark-preset-lint-recommended --save-dev
Bây giờ, thêm một script npm trong package.json của bạn:
/* … */
"scripts": {
/* … */
"format": "remark . --output",
/* … */
},
/* … */
💡 Mẹo: thêm ESLint và những thứ tương tự trong script
formatnữa.
Quan sát rằng sự thay đổi trên thêm một script format, có thể chạy bằng npm run format. Nó chạy remark trên tất cả các tệp markdown (.) và viết lại chúng (--output). Chạy ./node_modules/.bin/remark --help để biết thêm thông tin về CLI.
Sau đó, thêm một remarkConfig vào package.json của bạn để cấu hình remark:
/* … */
"remarkConfig": {
"settings": {
"bullet": "*", // Use `*` for list item bullets (default)
// See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
},
"plugins": [
"remark-preset-lint-consistent", // Check that markdown is consistent.
"remark-preset-lint-recommended", // Few recommended rules.
[
// Generate a table of contents in `## Contents`
"remark-toc",
{
"heading": "contents"
}
]
]
},
/* … */
👉 Ghi chú: bạn phải loại bỏ các chú thích trong các ví dụ ở trên khi sao chép/dán chúng, vì các chú thích không được hỗ trợ trong các tệp
package.json.
Cuối cùng, bạn có thể chạy script npm để kiểm tra và định dạng các tệp markdown trong dự án của bạn:
npm run format
Cú pháp
remark tuân theo CommonMark, tiêu chuẩn hóa sự khác biệt giữa các phiên bản markdown, theo mặc định. Một số phần mở rộng cú pháp được hỗ trợ thông qua các tiện ích.
Chúng tôi sử dụng micromark cho quá trình phân tích cú pháp. Xem tài liệu của nó để biết thêm thông tin về markdown, CommonMark và các phần mở rộng.
Cây cú pháp
Định dạng cây cú pháp được sử dụng trong remark là mdast. Nó biểu thị cấu trúc markdown dưới dạng các đối tượng JSON.
Markdown này:
## Hello *Pluto*!
cho ra cây sau đây:
{
type: 'heading',
depth: 2,
children: [
{type: 'text', value: 'Hello '},
{type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
{type: 'text', value: '!'}
]
}
Loại
Tổ chức remark và tổ hợp thống nhất như là một toàn bộ đã được đánh dấu kiểu hoàn toàn với TypeScript. Các loại cho mdast có sẵn trong @types/mdast.
Để TypeScript hoạt động, việc gán kiểu cho các tiện ích của bạn một cách chính xác là vô cùng quan trọng. Chúng tôi mạnh mẽ khuyến nghị sử dụng kiểu Plugin từ unified với kiểu chung của nó và sử dụng các loại node cho các cấu trúc cú pháp do @types/mdast cung cấp.
/**
* @typedef {import('mdast').Root} Root
*
* @typedef Options
* Configuration (optional).
* @property {boolean} [someField]
* Some option.
*/
// To type options and that the it works with `mdast`:
/** @type {import('unified').Plugin<[Options?], Root>} */
export function myRemarkPluginAcceptingOptions(options) {
// `options` is `Options?`.
return function (tree, file) {
// `tree` is `Root`.
}
}
Tương thích
Các dự án được duy trì bởi tổ hợp thống nhất tương thích với tất cả các phiên bản Node.js được duy trì. Hiện tại, đó là Node.js 12.20+, 14.14+ và 16.0+. Các dự án của chúng tôi đôi khi hoạt động với các phiên bản cũ hơn, nhưng điều này không được đảm bảo.
Bảo mật
Vì markdown có thể được chuyển thành HTML và việc sử dụng không đúng cách HTML có thể mở cửa cho các cuộc tấn công cross-site scripting (XSS), việc sử dụng remark có thể không an toàn. Khi chuyển sang HTML, bạn có thể kết hợp remark với rehype, trong trường hợp đó bạn nên sử dụng rehype-sanitize.
Việc sử dụng các tiện ích của remark cũng có thể mở cửa cho các cuộc tấn công khác. Hãy đánh giá cẩn thận từng tiện ích và các rủi ro liên quan đến việc sử dụng chúng.
Để biết thông tin về cách báo cáo một vấn đề, xem security policy của chúng tôi.
Đóng góp
Xem contributing.md trong remarkjs/.github để biết cách bắt đầu. Xem support.md để biết cách nhận sự trợ giúp. Tham gia cùng chúng tôi trong Discussions để trò chuyện với cộng đồng và các đóng góp viên.
Dự án này có một code of conduct. Bằng cách tương tác với kho lưu trữ này, tổ chức hoặc cộng đồng, bạn đồng ý tuân theo các điều khoản của nó.
Chi tiết Tải xuống:
Tác giả: remarkjs
Mã Nguồn: https://github.com/remarkjs/remark
Giấy phép: MIT license
