Creation:2025-02-07Last update:2026-05-19

    Markdown / 富文本内容

    Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以轻松编写和维护具有丰富格式的内容，例如博客、文章等。

    声明 Markdown 内容

    您可以使用 md 函数声明 Markdown 内容，或简单地将其作为字符串声明（如果它包含 Markdown 语法）。

    从 8.10.0 版本开始，您可以在 .content.md 文件中直接声明 Markdown 内容。Intlayer 会自动检测并解析 Markdown 内容。

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: 我的内容locale: en---# 我的内容这里是一个 Markdown 内容示例

    locale front-matter 字段是定义内容语言环境的字段。它是可选的。如果没有提供，Intlayer 会使用默认语言环境，如果没有提供特定语言环境的翻译，这也将作为后备语言环境。

    文件结构示例：

    text
    content├── markdown-file.en.content.md├── markdown-file.fr.content.md└── markdown-file.es.content.md

    您可以在 front-matter 中添加任何在字典定义中定义的属性。

    渲染 Markdown

    Intlayer 提供两种独立的方式来渲染 Markdown：

    1. 通过 useIntlayer — Intlayer 会自动将 md 节点转换为框架的原生输出（JSX，VNode，HTML 字符串）。

      • Frontmatter 被解析并作为 .metadata 暴露。您可以在两个级别上覆盖渲染 — 使用 MarkdownProvider（或框架等效物）进行全局覆盖，或使用 .use() 针对每个节点进行局部覆盖。两者可以结合使用；.use() 优先于 MarkdownProvider，而 MarkdownProvider 优先于默认渲染。

    2. 辅助实用程序 — <MarkdownRenderer />，useMarkdownRenderer() 和 renderMarkdown() 是独立的工具，仅接受原始 Markdown 字符串。它们独立于 useIntlayer，不与它返回的修饰节点一起工作。

    Markdown 渲染支持 MDX — 在您的 Markdown 中直接按名称使用任何 JSX/框架组件。

    1. 自动渲染（通过 useIntlayer）

    Markdown 节点可以直接呈现为 JSX。

    App.tsx
    import { useIntlayer } from "react-intlayer";import { MarkdownProvider } from "react-intlayer/markdown";const AppContent = () => {  const { myMarkdownContent } = useIntlayer("app");  return <div>{myMarkdownContent}</div>;};const App = () => (  <MarkdownProvider    components={{      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,      MyButton: (props) => <button {...props} />, // MDX 组件    }}  >    <AppContent />  </MarkdownProvider>);
    如果没有提供 MarkdownProvider，Intlayer 将使用默认的 Markdown 转 JSX 解析器渲染 markdown。

    您还可以使用 .use() 方法提供特定节点的局部覆盖：

    tsx
    {myMarkdownContent.use({  h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,})}

    您可以以字符串形式检索 Markdown：

    tsx
    {myMarkdownContent.value}{String(myMarkdownContent)}{myMarkdownContent.toString()}

    您可以像这样访问您的 markdown 元数据：

    tsx
    {myMarkdownContent.metadata}{myMarkdownContent.metadata.title}

    2. 辅助实用程序（仅限 Markdown 字符串）

    这些实用程序渲染 仅限原始 Markdown 字符串 且独立于 useIntlayer。当您需要从词典以外的来源渲染 Markdown 时使用它们。

    <MarkdownRenderer /> 组件

    使用特定选项渲染 Markdown 字符串。

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# 我的标题"}</MarkdownRenderer>

    useMarkdownRenderer() 钩子

    获取预配置的渲染器函数。

    tsx
    import { useMarkdownRenderer } from "react-intlayer/markdown";const renderMarkdown = useMarkdownRenderer({  forceBlock: true,  components: { h1: (props) => <h1 {...props} className="custom" /> }});return renderMarkdown("# 我的标题");

    renderMarkdown() 实用程序

    组件外部渲染的独立实用程序。

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# 我的标题", { forceBlock: true });

    使用 MarkdownProvider 进行全局配置

    MarkdownProvider（或其框架对应的组件）为整个应用程序配置 Markdown 渲染管道。它适用于自动 useIntlayer 渲染和辅助实用程序。此处设置的选项为默认值 — .use() 在节点级别将其覆盖。

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    components={{      h1: (props) => <h1 style={{color: 'green'}} {...props} />,      a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,      MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,    }}  >    {children}  </MarkdownProvider>);
    支持 MDX — Markdown 内部使用的任何组件名称（例如 <MyCustomJSXComponent />）都会根据 components 映射进行解析。

    您还可以使用自己的 markdown 渲染器：

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    renderMarkdown={async (md) => {      // Use dynamic import to reduce the bundle size of your application      const { renderMarkdown } = await import('react-intlayer/markdown');      return renderMarkdown(md);    }}  >    {children}  </MarkdownProvider>);
    动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。

    Suspense (悬念)

    Intlayer Markdown渲染器是动态加载的。虽然经过优化，但底层解析器块的大小约为55kb。同步加载会延迟初始页面渲染，并降低首次内容绘制（FCP）。

    为防止阻塞UI，Intlayer集成了React的Suspense API。它在后台获取解析器，并在下载期间抛出Promise。

    将渲染Intlayer Markdown的任何组件包装在<Suspense>边界中。这会在下载块时显示本地化的后备状态，从而允许立即渲染DOM的其余部分。

    警告：如果不提供<Suspense>边界，React将在根级别暂停或阻止整个组件树的渲染，直到55kb的块完全加载完毕。

    在Next.js App Router中，您可以为客户端组件使用React Suspense，或为服务器组件使用loading.tsx文件。

    客户端组件：

    components/MyComponent.tsx
    "use client";import { useIntlayer } from "next-intlayer";import { Suspense } from "react";const MyComponent = () => {const markdownContent = useIntlayer("my-markdown");return (  <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>);};

    带有loading.tsx的服务器组件：

    app/loading.tsx
    export default function Loading() {return <div>Loading...</div>;}
    app/page.tsx
    import { useIntlayer } from "next-intlayer/server";const MyPage = () => {const markdownContent = useIntlayer("my-markdown");return <div>{markdownContent}</div>;};export default MyPage;

    服务端渲染 (SSR) 与 注水 (Hydration)

    与其他 Markdown 解析器（如 remark / rehype）相比，Intlayer Markdown 无依赖关系，且既可以在客户端运行，也可以在服务端运行。

    但是 Intlayer 针对服务端渲染 (SSR) 框架（如 Next.js App Router, React Router, Nuxt, SvelteKit 等）进行了解析优化。

    Intlayer 允许您在服务端将 Markdown 预解析为抽象语法树 (AST)，而不是将原始 Markdown 字符串发送到客户端并在浏览器中解析（这会带来性能损失）。

    您可以在服务端使用框架的 Intlayer 包中的 parseMarkdown 函数来生成可序列化的 AST（ParsedMarkdown 对象），并将其直接传递给前端。所有 Intlayer 渲染工具（如 <MarkdownRenderer>、useMarkdownRenderer 等）都会自动接受此 AST 对象并无缝渲染它。

    服务端/客户端架构中的示例

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. 在服务端：将 markdown 解析为可序列化的 ASTexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // 将 AST 作为 JSON 返回给客户端  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. 在客户端：直接渲染 AST，无需重新解析export default function Page() {  const { content } = useLoaderData();  // 渲染器既接受原始字符串，也接受解析后的 AST  return <MarkdownRenderer content={content} />;}

    这种模式确保 Markdown 解析逻辑完全在服务端执行，从而显著减少客户端执行时间，并提高初始注水速度。

    选项参考

    这些选项可传递给MarkdownProvider、MarkdownRenderer、useMarkdownRenderer和renderMarkdown。

    Option Type Default 描述
    forceBlock boolean false 强制将输出包装在块级元素（例如<div>）中。
    forceInline boolean false 强制将输出包装在内联元素（例如<span>）中。
    tagfilter boolean true 启用GitHub标签过滤器以通过剥离危险的HTML标签来提高安全性。
    preserveFrontmatter boolean false 如果为true，则不会剥离Markdown字符串开头的frontmatter。
    components Overrides {} HTML标签到自定义组件的映射（例如{ h1: MyHeading }）。
    wrapper Component null 用于包装渲染Markdown的自定义组件。
    renderMarkdown Function null 自定义渲染函数，用于完全替换默认的Markdown编译器。
    嵌套
    HTML