@mdit/plugin-snippet

Plugin to import code snippets in markdown.

Usage

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:

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

Escaping

You can escape < by \
```
\<<< test.js
```
will be
<<< test.js

Options

currentPath

Type: (env: any) => string
Required: Yes
Details: Get current filePath.

resolvePath

Type: (path: string, cwd: string | null) => string
Default: (path) => path
Details: Handle include filePath.

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>