跳至主要內容

@mdit/plugin-include

在 Markdown 中包含其他文件的插件。

使用 仅限 Node.js 环境

TS
import MarkdownIt from "markdown-it";
import { include } from "@mdit/plugin-include";

const mdIt = MarkdownIt().use(include, {
  // 你的选项，currentPath 是必填的
  currentPath: (env) => env.filePath,
});

mdIt.render("<!-- @include: ./path/to/include/file.md -->", {
  filePath: "path/to/current/file.md",
});

由于 markdown-it 仅在 render() api 中接收 markdown 内容，因此插件不知道当前内容的文件路径，因此不知道在哪里可以找到包含文件。

要解决这个问题，你应该通过 env 对象传递信息，并在插件选项中设置 currentPath。

currentPath 函数将接收 env 对象并返回当前文件的路径。

此外，要支持别名，你可以在插件选项中设置 resolvePath。

例如，以下代码添加了对 @src 别名的支持：

const MarkdownIt = require("markdown-it");
const { include } = require("@mdit/plugin-include");

const mdIt = MarkdownIt();

mdIt.use(include, {
  currentPath: (env) => env.filePath,
  resolvePath: (path, cwd) => {
    if (path.startsWith("@src")) {
      return path.replace("@src", "path/to/src/folder");
    }

    return path.join(cwd, path);
  },
});

此外，默认情况下，包含文件中的图像和链接将相对于导入的文件进行解析，但是你可以通过在插件选项中将 resolveImagePath 和 resolveLinkPath 设置为 false 来更改此行为。

此外，该插件支持 deep 功能，如果此选项设置为 true，它将处理包含文件中嵌套的 @include。

格式

使用 <!-- @include: filename --> 导入文件。

如果要部分导入文件，你可以指定导入的行数

  • <!-- @include: filename{start-end} -->
  • <!-- @include: filename{start-} -->
  • <!-- @include: filename{-end} -->

同时你也可以导入文件区域:

  • <!-- @include: filename#region -->

文件区域

文件区域是 vscode 中的一个概念，区域内容被 #region 和 #endregion 注释包围。

这里有些例子：

HTML
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <!-- region snippet -->
    <p>
      Lorem ipsum dolor, sit amet consectetur adipisicing elit. Eligendi,
      repellendus. Voluptatibus alias cupiditate at, fuga tenetur error officiis
      provident quisquam autem, porro facere! Neque quibusdam animi quaerat
      eligendi recusandae eaque.
    </p>
    <!-- endregion snippet -->
    <p>
      Veniam harum illum natus omnis necessitatibus numquam architecto eum
      dignissimos, quos a adipisci et non quam maxime repellendus alias ipsum,
      vero praesentium laborum commodi perferendis velit repellat? Vero,
      cupiditate sequi.
    </p>
  </body>
</html>

嵌套与转义

  • 你可以在选项中设置 deep: true 让插件递归处理导入 Markdown 文件的 <!-- @include: --> 语法。

  • 你可以通过在 <-- @include --> 语法之前添加零宽空格 (U+200B or &#8203;) 来转义:

    &#8203;<!-- @include: ./demo.snippet.md -->

    会被渲染为

    ​

选项

interface MarkdownItIncludeOptions {
  /**
   * 获得当前文件路径
   *
   * @default (path) => path
   */
  currentPath: (env: any) => string;

  /**
   * 处理 include 文件路径
   *
   * @default (path) => path
   */
  resolvePath?: (path: string, cwd: string | null) => string;

  /**
   * 是否深度导入包含的 Markdown 文件
   *
   * @default false
   */
  deep?: boolean;

  /**
   * 是否使用 `<!-- @include: xxx -->` 代替 `@include: xxx` 导入文件
   *
   * @default true
   */
  useComment?: boolean;

  /**
   * 是否解析包含的 Markdown 文件的里的相对图像路径
   *
   * @default true
   */
  resolveImagePath?: boolean;

  /**
   * 是否解析包含的 Markdown 文件的里的文件相对路径
   *
   * @default true
   */
  resolveLinkPath?: boolean;
}

示例

<!-- @include: ./demo.snippet.md -->:

二级标题

内容包含加粗文字和一些其他增强内容:

提示

你最近怎么样了? 😄

<!-- @include: ./demo.snippet.md{9-13} -->:

提示

你最近怎么样了? 😄

<!-- @include: ./demo.snippet.md#snippet -->:

内容包含加粗文字和一些其他增强内容:

demo.snippet.md 的内容
## 二级标题

<!-- #region snippet -->

内容包含**加粗文字**和一些其他增强内容:

<!-- #endregion snippet -->

::: tip

你最近怎么样了? :smile:

:::