Import files
About 450 wordsAbout 2 min
2025-03-25
Overview
The theme supports importing file slices in Markdown files.
Importing files is enabled by default, and you can also customize the behavior through configuration.
export default defineUserConfig({
theme: plumeTheme({
markdown: {
include: {
// ... options
},
}
})
})
Syntax
Use <!-- @include: filename -->
to import a file.
If you want to import a portion of the file, you can specify the line numbers:
<!-- @include: filename{start-end} -->
<!-- @include: filename{start-} -->
<!-- @include: filename{-end} -->
You can also import file regions:
<!-- @include: filename#region -->
File Regions
File regions are a concept in VSCode, where the content is enclosed by #region
and #endregion
comments.
<!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 { include } from '@mdit/plugin-include'
import MarkdownIt from 'markdown-it'
// #region snippet
const mdIt = MarkdownIt().use(include, {
// your options, currentPath is required
currentPath: env => env.filePath,
})
// #endregion snippet
mdIt.render('<!-- @include: ./path/to/include/file.md -->', {
filePath: 'path/to/current/file.md',
})
const { include } = require('@mdit/plugin-include')
const MarkdownIt = require('markdown-it')
// #region snippet
const mdIt = MarkdownIt().use(include, {
// your options, currentPath is required
currentPath: env => env.filePath,
})
// #endregion snippet
mdIt.render('<!-- @include: ./path/to/include/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
}
}
#include <iostream>
#include <vector>
std::vector<int> v;
#pragma region snippet
int f() {
for (int item : v) std::cout << item << std::endl;
return v.size();
}
#pragma endregion snippet
int main() {
int n, u;
std::cin >> n;
for (int i = 1; i <= n; ++i) {
std::cin >> u;
v.push_back(u);
}
std::cout << f();
return 0;
}
Configuration
You can also set an object to customize the file path and inclusion behavior.
interface IncludeOptions {
/**
* Process the include file path
*
* @default (path) => path
*/
resolvePath?: (path: string, cwd: string | null) => string
/**
* Whether to deeply import included Markdown files
*
* @default false
*/
deep?: boolean
/**
* Whether to use `<!-- @include: xxx -->` instead of `@include: xxx` to import files
*
* @default true
*/
useComment?: boolean
/**
* Whether to resolve relative image paths in included Markdown files
*
* @default true
*/
resolveImagePath?: boolean
/**
* Whether to resolve relative file paths in included Markdown files
*
* @default true
*/
resolveLinkPath?: boolean
}
For example: You can use @src
as an alias for the source folder.
export default defineUserConfig({
theme: plumeTheme({
markdown: {
include: {
resolvePath: (file) => {
if (file.startsWith('@src'))
return file.replace('@src', path.resolve(__dirname, '..'))
return file
},
},
}
})
})
Additionally, if you want to place Markdown files next to the actual files but do not want them to be rendered as pages, you can set the pagePatterns
option in the VuePress configuration. For more details, see pagePatterns.
export default defineUserConfig({
// Now any file with the `.snippet.md` extension will not be rendered as a page
pagePatterns: ['**/*.md', '!**/*.snippet.md', '!.vuepress', '!node_modules'],
theme: plumeTheme({
markdown: {
include: true
}
})
})
Examples
There is a foo.snippet.md
file in the project:
### Level 3 Heading
This is the content of the `foo.snippet.md` file.
::: info
Content of the info container
:::
<!-- region snippet -->
This is the content wrapped by `<!-- region snippet -->`.
It can be imported via `<!-- @include: ./foo.snippet.md#snippet -->`.
<!-- endregion snippet -->
Import the file using <!-- @include: ./foo.snippet.md -->
:
Include by file
Level 3 Heading
This is the content of the foo.snippet.md
file.
Info
Content of the info container
This is the content wrapped by <!-- region snippet -->
.
It can be imported via <!-- @include: ./foo.snippet.md#snippet -->
.
Import lines 5 to 7 of the file using <!-- @include: ./foo.snippet.md{5-7} -->
:
Include by lines
Info
Content of the info container
Import the snippet
region using <!-- @include: ./foo.snippet.md#snippet -->
:
Include by file region
This is the content wrapped by <!-- region snippet -->
.
It can be imported via <!-- @include: ./foo.snippet.md#snippet -->
.