MDX và React

Docusaurus có hỗ trợ tích hợp cho MDX, cho phép bạn viết JSX trong các tệp Markdown của bạn và hiển thị chúng dưới dạng các thành phần React.

Kiểm tra tài liệu MDX để xem những thứ ưa thích bạn có thể làm với MDX.

Gỡ lỗi MDX Định dạng MDX khá nghiêm ngặt và bạn có thể gặp lỗi biên dịch.

Sử dụng sân chơi MDX để gỡ lỗi chúng và đảm bảo cú pháp của bạn hợp lệ.

Thông tin Prettier, trình định dạng phổ biến nhất, chỉ hỗ trợ MDX v1 cũ. Nếu bạn nhận được kết quả định dạng không chủ ý, bạn có thể muốn thêm trước khu vực có vấn đề hoặc thêm vào khu vực của bạn cho đến khi Prettier có hỗ trợ thích hợp cho MDX v3. Một trong những tác giả chính của MDX khuyên bạn nên sử dụng remark-cli với remark-mdx.*.mdx.prettierignore

Xuất thành phần Để xác định bất kỳ thành phần tùy chỉnh nào trong tệp MDX, bạn phải xuất nó: chỉ các đoạn văn bắt đầu bằng sẽ được phân tích cú pháp thành thành phần thay vì văn xuôi.export

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!

Lưu ý cách nó hiển thị cả markup từ thành phần React của bạn và cú pháp Markdown:

Màu xanh lá cây Docusaurus và xanh Facebook là những màu yêu thích của tôi.
Tôi có thể viết Markdown cùng với JSX của mình!

MDX là JSX
Vì tất cả các tệp doc đều được phân tích cú pháp bằng MDX, bất cứ thứ gì trông giống như HTML thực sự là JSX. Do đó, nếu bạn cần tạo kiểu cho một thành phần, hãy làm theo phiên bản JSX và cung cấp các đối tượng kiểu.

/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>

Nhập thành phần Bạn cũng có thể nhập các thành phần của riêng mình được xác định trong các tệp khác hoặc các thành phần của bên thứ ba được cài đặt qua npm.

<!-- Docusaurus theme component -->
import TOCInline from '@theme/TOCInline';
<!-- External component -->
import Button from '@mui/material/Button';
<!-- Custom component -->
import BrowserWindow from '@site/src/components/BrowserWindow';

mẹo
Bí danh trỏ đến thư mục trang web của bạn, thường là nơi có tệp. Sử dụng bí danh thay vì đường dẫn tương đối () giúp bạn không phải cập nhật đường dẫn nhập khi di chuyển tệp xung quanh hoặc khi lập phiên bản tài liệu và dịch.@sitedocusaurus.config.js'../../src/components/BrowserWindow'

Mặc dù khai báo các thành phần trong Markdown rất thuận tiện cho các trường hợp đơn giản, nhưng nó trở nên khó duy trì vì hỗ trợ trình chỉnh sửa hạn chế, rủi ro lỗi phân tích cú pháp và khả năng tái sử dụng thấp. Sử dụng một tệp riêng biệt khi thành phần của bạn liên quan đến logic JS phức tạp:.js

src/components/Highlight.js import React from 'react';

export default function Highlight({children, color}) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '2px',
        color: '#fff',
        padding: '0.2rem',
      }}>
      {children}
    </span>
  );
}

đánh dấu-file.mdx

import Highlight from '@site/src/components/Highlight';

<Highlight color="#25c2a0">Docusaurus green</Highlight>

mẹo
Nếu bạn sử dụng cùng một thành phần trên nhiều tệp, bạn không cần phải nhập nó ở mọi nơi—hãy cân nhắc thêm nó vào phạm vi chung. Xem bên dưới

Phạm vi thành phần MDX Ngoài việc nhập một thành phần và xuất một thành phần, cách thứ ba để sử dụng một thành phần trong MDX là đăng ký nó vào phạm vi toàn cầu, điều này sẽ làm cho nó tự động có sẵn trong mọi tệp MDX mà không cần bất kỳ câu lệnh nhập nào.

Ví dụ: cho tệp MDX này:

- a
- list!

And some <Highlight>custom markup</Highlight>...

Nó sẽ được biên dịch thành một thành phần React chứa , , và các phần tử. không phải là một phần tử HTML gốc: bạn cần cung cấp triển khai thành phần React của riêng bạn cho nó.ullipHighlightHighlight

Trong Docusaurus, phạm vi thành phần MDX được cung cấp bởi tập tin. Nó không phải là một thành phần React, không giống như hầu hết các lần xuất khác dưới bí danh: nó là một bản ghi từ tên thẻ như đến việc triển khai thành phần React của chúng.@theme/MDXComponents@theme/Highlight

Nếu bạn xoay thành phần này, bạn sẽ tìm thấy tất cả các thẻ đã được triển khai và bạn có thể tùy chỉnh thêm việc triển khai của chúng tôi bằng cách xoay thành phần phụ tương ứng, như (được sử dụng để hiển thị các khối mã Markdown).@theme/MDXComponents/Code

Nếu bạn muốn đăng ký thêm tên thẻ (như thẻ ở trên), bạn nên xem xét gói @theme / MDXComponents, vì vậy bạn không phải duy trì tất cả các ánh xạ hiện có. Vì CLI xoay chưa cho phép gói các tệp không phải thành phần, bạn nên tạo trình bao bọc theo cách thủ công:

<Highlight>

src/theme/MDXComponents.js

import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';

export default {
  // Re-use the default mapping
  ...MDXComponents,
  // Map the "<Highlight>" tag to our Highlight component
  // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
  Highlight,
};

Và giờ đây, bạn có thể thoải mái sử dụng trong từng trang mà không cần viết câu lệnh import:

<Highlight>

I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

Tôi có thể thuận tiện sử dụng Docusaurus màu xanh lá cây ở mọi nơi!

cảnh báo
Chúng tôi sử dụng tên thẻ viết hoa như có chủ đích.Highlight

Từ MDX v3+ trở đi (Docusaurus v3+), tên thẻ viết thường luôn được hiển thị dưới dạng phần tử html gốc và sẽ không sử dụng bất kỳ ánh xạ thành phần nào bạn cung cấp.

cảnh báo
Tính năng này được cung cấp bởi MDXProvider. Nếu bạn đang nhập Markdown trong trang React, bạn phải tự cung cấp nhà cung cấp này thông qua thành phần chủ đề.MDXContent

src/pages/index.js

import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';

export default function LandingPage() {
  return (
    <div>
      <MDXContent>
        <FeatureDisplay />
      </MDXContent>
    </div>
  );
}

Nếu bạn không bao bọc MDX đã nhập của mình bằng , phạm vi toàn cầu sẽ không khả dụng.MDXContent

Khả năng tương tác của Markdown và JSX Docusaurus v3 đang sử dụng MDX v3.

Cú pháp MDX chủ yếu tương thích với CommonMark, nhưng nghiêm ngặt hơn nhiều vì các tệp của bạn có thể sử dụng JSX và được biên dịch thành các thành phần React thực sự (kiểm tra sân chơi)..mdx

Một số tính năng hợp lệ của CommonMark sẽ không hoạt động với MDX (thêm thông tin), đáng chú ý:

Các khối mã thụt lề: sử dụng ba lần đánh dấu ngược để thay thế Liên kết tự động (): thay thế sử dụng cú pháp liên kết thông thường

(<http://localhost:3000>[http://localhost:3000](http://localhost:3000))

Cú pháp HTML (): sử dụng JSX thay thế

(<p style="color: red;"><p style={{color: 'red'}}>)

Unescaped và : escape chúng bằng thay thế

( và {<\\{\<)

Hỗ trợ CommonMark thử nghiệm
Docusaurus v3 cho phép bạn có thể chọn tham gia hỗ trợ CommonMark tiêu chuẩn, ít nghiêm ngặt hơn với các tùy chọn sau:

Vấn đề phía trướcmdx.format: md
Phần mở rộng tệp kết hợp với cấu hình.mdsiteConfig.markdown.format: "detect"
Tính năng này là thử nghiệm và hiện có một số hạn chế.

Nhập đoạn mã Bạn không chỉ có thể nhập một tệp chứa định nghĩa thành phần mà còn có thể nhập bất kỳ tệp mã nào dưới dạng văn bản thô, và sau đó chèn nó vào một khối mã, nhờ Webpack raw-loader. Để sử dụng , trước tiên bạn cần cài đặt nó trong dự án của mình:raw-loader

npm Sợi PNPM

npm install --save raw-loader

Bây giờ bạn có thể nhập đoạn mã từ một tệp khác như vậy:

myMarkdownFile.mdx

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

import React, {useState} from 'react';

export default function MyComponent() {
  const [bool, setBool] = useState(false);
  return (
    <div>
      <p>MyComponent rendered !</p>
      <p>bool={bool ? 'true' : 'false'}</p>
      <p>
        <button onClick={() => setBool((b) => !b)}>toggle bool</button>
      </p>
    </div>
  );
}

Xem sử dụng các khối mã trong JSX để biết thêm chi tiết về thành phần.

<CodeBlock>

ghi
Bạn phải sử dụng thay vì Markdown triple-backtick , bởi vì sau này sẽ gửi ra bất kỳ nội dung nào của nó nguyên trạng, nhưng bạn muốn nội suy văn bản đã nhập ở đây.<CodeBlock>```

cảnh báo
Tính năng này là thử nghiệm và có thể bị thay đổi API trong tương lai.

Nhập Markdown Bạn có thể sử dụng các tệp Markdown làm thành phần và nhập chúng ở nơi khác, trong các tệp Markdown hoặc trong các trang React. Mỗi tệp MDX mặc định xuất nội dung trang của nó dưới dạng thành phần React. Trong câu lệnh, bạn có thể nhập mặc định thành phần này với bất kỳ tên nào, nhưng nó phải được viết hoa theo quy tắc đặt tên của React.import

Theo quy ước, sử dụng tiền tố tên tệp _ sẽ không tạo bất kỳ trang tài liệu nào và có nghĩa là tệp Markdown là một "phần", được nhập bởi các tệp khác.

_markdown-một phần-ví dụ.mdx

<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.

someOtherDoc.mdx

import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />

Xin chào Sebastien
Đây là văn bản một số nội dung từ._markdown-partial-example.md

Bằng cách này, bạn có thể sử dụng lại nội dung giữa nhiều trang và tránh trùng lặp tài liệu.

Xuất khẩu có sẵn Trong trang MDX, các biến sau có sẵn dưới dạng toàn cục:

frontMatter: vấn đề phía trước như một bản ghi của các khóa và giá trị chuỗi; toc: mục lục, như một cây tiêu đề. Xem thêm Mục lục nội tuyến để biết trường hợp sử dụng cụ thể hơn. contentTitle: tiêu đề Markdown, là tiêu đề đầu tiên trong văn bản Markdown. Đó là nếu không có (ví dụ: tiêu đề được chỉ định ở vấn đề phía trước).h1undefined

import TOCInline from '@theme/TOCInline';
import CodeBlock from '@theme/CodeBlock';

The table of contents for this page, serialized:

<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>

The front matter of this page:

<ul>
  {Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
</ul>

<p>The title of this page is: <b>{contentTitle}</b></p>

Mục lục của trang này, được nối tiếp:

[
  {
    "value": "Exporting components",
    "id": "exporting-components",
    "level": 3
  },
  {
    "value": "Importing components",
    "id": "importing-components",
    "level": 3
  },
  {
    "value": "MDX component scope",
    "id": "mdx-component-scope",
    "level": 3
  },
  {
    "value": "Markdown and JSX interoperability",
    "id": "markdown-and-jsx-interoperability",
    "level": 3
  },
  {
    "value": "Importing code snippets",
    "id": "importing-code-snippets",
    "level": 2
  },
  {
    "value": "Importing Markdown",
    "id": "importing-markdown",
    "level": 2
  },
  {
    "value": "Available exports",
    "id": "available-exports",
    "level": 2
  }
]

Vấn đề phía trước của trang này:

ID: Phản ứng mô tả: Sử dụng sức mạnh của React trong tài liệu Docusaurus Markdown, nhờ MDX sên: /markdown-features/react Tiêu đề của trang này là: MDX và React