@mdit/plugin-snippet
用于在 Markdown 中导入代码片段的插件。
使用 仅限 Node.js 环境
import { snippet } from "@mdit/plugin-snippet";
import MarkdownIt from "markdown-it";
const mdIt = new MarkdownIt().use(snippet, {
// 你的选项,currentPath 是必填的
currentPath: (env) => env.filePath,
});
mdIt.render("<<< example.ts", {
filePath: "path/to/current/file.md",
});由于 markdown-it 仅在 render() api 中接收 markdown 内容,因此插件不知道当前内容的文件路径,因此不知道在哪里可以找到包含文件。
要解决这个问题,你应该通过 env 对象传递信息,并在插件选项中设置 currentPath。
currentPath 函数将接收 env 对象并返回当前文件的路径。
此外,要支持别名,你可以在插件选项中设置 resolvePath。
例如,以下代码添加了对 @src 别名的支持:
import { join } from "node:path";
import { snippet } from "@mdit/plugin-snippet";
import MarkdownIt from "markdown-it";
const mdIt = new MarkdownIt();
mdIt.use(snippet, {
currentPath: (env) => env.filePath,
resolvePath: (path, cwd) => {
if (path.startsWith("@src")) {
return path.replace("@src", "path/to/src/folder");
}
return cwd ? join(cwd, path) : path;
},
});语法
使用 <<< filename 截取代码片段。 如果你想突出显示特定的行,你可以使用 {lines} 来做到这一点。
你也可以在末尾使用 #regionName 截取文件区域。
例子:
<<< example.html导入example.html作为片段<<< example.js{1,3,7-9}。 将example.js作为代码段导入并突出显示第 1、3、7 到 9 行<<< example.css#normalize在example.css中导入normalize片段<<< example.ts#plugin{2-5}在example.ts中导入plugin片段并突出显示第 2 到 5 行
注
行高亮需要其他插件支持,插件只提供高亮信息给代码块。
文件区域
文件区域是 vscode 中的一个概念,区域内容被 #region 和 #endregion 注释包围。
这里有些例子:
<!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>## Hello world
<!-- #region snippet -->
Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptates
inventore iure quo aut doloremque, ipsum ab voluptatem ipsa, velit laborum
illo quae omnis reiciendis hic, ut dolorem non debitis in!
<!-- #endregion snippet -->
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.import { snippet } from "@mdit/plugin-snippet";
import MarkdownIt from "markdown-it";
// #region snippet
const mdIt = new MarkdownIt().use(snippet, {
// 你的选项,currentPath 是必填的
currentPath: (env) => env.filePath,
});
// #endregion snippet
mdIt.render("<<< ./path/to/snippet/file.md", {
filePath: "path/to/current/file.md",
});import { snippet } from "@mdit/plugin-snippet";
import MarkdownIt from "markdown-it";
// #region snippet
const mdIt = new MarkdownIt().use(snippet, {
// 你的选项,currentPath 是必填的
currentPath: (env) => env.filePath,
});
// #endregion snippet
mdIt.render("<<< ./path/to/snippet/file.md", {
filePath: "path/to/current/file.md",
});html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}public class HelloWorld {
// #region snippet
public static void main(String args[]){
System.out.println("Hello World");
}
// #endregion snippet
}class MyClass:
msg = "world"
#region snippet
def sayHello(self):
print("Hello " + self.msg + "!")
#region snippet
def sayBye(self):
print("Bye " + self.msg + "!")Imports System
Module Module1
# Region snippet
Sub Main()
Console.WriteLine("Hello World!")
Console.WriteLine("Press Enter Key to Exit.")
Console.ReadLine()
End Sub
# EndRegion
End Module>nul 2>&1 "%SYSTEMROOT%\system32\cacls.exe" "%SYSTEMROOT%\system32\config\system"
if '%errorlevel%' NEQ '0' (
echo Requesting administrative privileges...
goto UACPrompt
) else ( goto gotAdmin )
::#region snippet
:UACPrompt
echo Set UAC = CreateObject^("Shell.Application"^) > "%temp%\getadmin.vbs"
echo UAC.ShellExecute "%~s0", "", "", "runas", 1 >> "%temp%\getadmin.vbs"
"%temp%\getadmin.vbs"
exit /B
::#endregion snippet
:gotAdmin
if exist "%temp%\getadmin.vbs" ( del "%temp%\getadmin.vbs" )
pushd "%CD%"
CD /D "%~dp0"using System;
namespace HelloWorldApp {
class Geeks {
// #region snippet
static void Main(string[] args) {
// statement
// printing Hello World!
Console.WriteLine("Hello World!");
// To prevents the screen from
// running and closing quickly
Console.ReadKey();
}
// #endregion snippet
}
}转义
你可以通过
\来转义<\<<< test.js会被渲染为
<<< test.js
选项
(env: any) => string获取当前文件路径。
(path: string, cwd: string | null) => string(path) => path处理片段文件路径。
booleanfalse是否允许读取 projectRoot 之外的文件。即使启用,denyFiles 仍然生效。
stringprocess.cwd()项目根目录;相对路径按 process.cwd() 解析。它必须是已存在的目录,否则插件会在安装时抛错。
readonly (string | RegExp)[]defaultSensitiveFiles即使在 projectRoot 内也禁止读取的文件模式。传入时会替换默认列表;需要扩展时展开 defaultSensitiveFiles。
安全
默认情况下,插件只读取 projectRoot 内的文件,并拒绝匹配 defaultSensitiveFiles 的文件(例如 .env、私钥和 .git/**)。allowOutsideRoot: true 只会关闭根目录检查,denyFiles 仍然生效。
处理不可信的 Markdown 时,仍应在低权限或沙箱进程中构建。denylist 并非穷尽列表,不能替代沙箱隔离。
denyFiles 会替换默认列表。需要扩展时展开 defaultSensitiveFiles:
import { defaultSensitiveFiles, snippet } from "@mdit/plugin-snippet";
mdIt.use(snippet, {
// ...
denyFiles: [...defaultSensitiveFiles, "my-secret.json"],
});示例
<<< @snippets/example.css:
html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}<<< @snippets/example.ts#snippet:
const mdIt = new MarkdownIt().use(snippet, {
// your options, currentPath is required
currentPath: (env) => env.filePath,
});<<< @snippets/example.html#snippet{2-5}:
<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>