@mdit/plugin-include

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

使用

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 别名的支持：

import MarkdownIt from "markdown-it";
import { include } from "@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。

格式

使用  导入文件。

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

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

文件区域

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

这里有些例子：

嵌套与转义

你可以在选项中设置 deep: true 让插件递归处理导入 Markdown 文件的  语法。
你可以通过在 <-- @include --> 语法之前添加零宽空格 (U+200B or ) 来转义:
```
&#8203;
```
会被渲染为

选项

currentPath

类型：(env: any) => string
必填：是
详情：获取当前文件路径。

resolvePath

类型：(path: string, cwd: string | null) => string
默认值：(path) => path
详情：处理包含文件路径。

deep

类型：boolean
默认值：false
详情：是否深度导入包含的 Markdown 文件。

useComment

类型：boolean
默认值：true
详情：是否使用  代替 @include: xxx 导入文件。

resolveImagePath

类型：boolean
默认值：true
详情：是否解析包含的 Markdown 文件的里的相对图像路径。

resolveLinkPath

类型：boolean
默认值：true
详情：是否解析包含的 Markdown 文件的里的文件相对路径。

示例

:

二级标题

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

提示

你最近怎么样了? 😄

:

提示

你最近怎么样了? 😄

:

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

demo.snippet.md 的内容

## 二级标题

<!-- #region snippet -->

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

<!-- #endregion snippet -->

::: tip

你最近怎么样了? :smile:

:::