Markdown-it-import

An extensible Markdown-it plugin to import external files.

Attension: To be compatible with VuePress v2, markdown-it-import is now released as pure ESM packages.

Features

Currently, it supports the following files

• Markdown files: Similar to #include of C language, the nested import is supported.
• Code snippets

What's more, transclusion is also supported, like lines, fragement tags and regular expression.

Usage

npm i vuepress@next markdown-it-import -S

configure your config.js

import markdownItImport from 'markdown-it-import'

export default {
  extendsMarkdown: (md) => {
    md.use(markdownItImport);
  }
}

Example

Using @import(type, importPath, optional) in your markdown files, just like you call javascript function.

• type: string
• path: string
• others: Javascript Object

Import Markdown

Exclusive options:

• recursive: bool, whether to import recursively, default to true

Import markdown files without recursion.

@import('md', './test/simple-md-import.md', {recursive: false})

This is a simple markdown file, and it will import another markdown file.

The imported content is as follows:

@import('md', './imported.md')

Import markdown files recursively.

@import('md', './test/simple-md-import.md')

This is a simple markdown file, and it will import another markdown file.

The imported content is as follows:

This is what will be imported.

This is what will be imported.

Import code

Exclusive options:

• lang: string, the type of the language, default to the extension of file name.

@import('code', './test/helloworld.js', {lang: 'js'})

console.log('Hello World')

Using the transclusion parameter

Options of transclusion (in order of precedence):

• lines: Array, the line number you want to import
• fragement: string, the lines between fragement will be imported
• regex: Regex, the lines match the regex will be imported

The entire content of ./test/lines.txt is as follows

line 1
# tag1
line 3
line 4
# tag1
line 6
# tag2
line 8
line 9
line 10
line 11
line 12
line 13
line 14
line 15
line 16
line 17
# tag2
line 19
line 20
line 21

Import lines 3 to 8

@import('code', './test/lines.text', {lang: 'text', lines: [3, 8]})

line 3
line 4
# tag1
line 6
# tag2
line 8

Import lines 1, 3 to 5, and 8

@import('code', './test/lines.text', {lang: 'text', lines: [1, [3, 5], 8]})

line 1
line 3
line 4
# tag1
line 8

Import the content between # tag1

@import('code', './test/lines.text', {lang: 'text', fragment: '# tag1'})

line 3
line 4

Using regular expression to import lines 10 to 19

@import('code', './test/lines.text', {lang: 'text', regex: /line\s1[0-9]/})

line 10
line 11
line 12
line 13
line 14
line 15
line 16
line 17
line 19

Complex transclusion

@import('code', './test/lines.text', {lang: 'text', line: [6, 20], fragment: '# tag2', regex: /line\s[0-9]$/})

line 8
line 9