Skip to main content

@mdit/plugin-snippet

Plugin to import code snippets in markdown.

Usage Node.js runtime only

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

const mdIt = MarkdownIt().use(snippet, {
  // your options, currentPath is required
  currentPath: (env) => env.filePath,
});

mdIt.render("<<< example.ts", {
  filePath: "path/to/current/file.md",
});

Since markdown-it only receive markdown content in render() api, so the plugin don't know the file path of current content so don't know where to find the snippet files.

To solve this, you should pass the information via env object, and set currentPath in plugin options.

currentPath function will receive env object and should return path to current file.

Also, to support alias, you can set resolvePath in plugin options.

For example, the following code add support for @src alias:

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

const mdIt = MarkdownIt();

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

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

Syntax

Use <<< filename to snippet code snippets. If you want to highlight specific lines, you can use {lines} to do that.

Also you can snippet file region with #regionName at end.

E.g.:

  • <<< example.html import example.html as snippet
  • <<< example.js{1,3,7-9}. import example.js as snippet and highlight lines 1, 3, 7 to 9
  • <<< example.css#normalize import region normalize in example.css
  • <<< example.ts#plugin{2-5} import region plugin in example.ts and highlight lines 1 to 3

Note

Line highlight should be supported by other plugins, the plugin only provides information to code fence info.

File region

File region is a concept in vscode, where the region content is surrounded by #region and #endregion comments.

Here are some examples:

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>

Escaping

  • You can escape < by \

    \<<< test.js

    will be

    <<< test.js

Options

interface MarkdownItSnippetOptions {
  /**
   * Get current filePath
   *
   * @default (path) => path
   */
  currentPath: (env: any) => string;

  /**
   * handle include filePath
   *
   * @default (path) => path
   */
  resolvePath?: (path: string, cwd: string | null) => string;
}

Demo

<<< @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 = 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>