Skip to main content

Include Files

About 1 minMarkdownCode DemoInclude Files

Let the Markdown file in your VuePress site support including other files.

Settings

TS
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    plugins: {
      mdEnhance: {
        include: true,
      },
    },
  }),
});







 
 
 


Syntax

Use <!-- @include: filename --> to include a file.

To partially import the file, you can specify the range of lines to be included:

  • <!-- @include: filename{start-end} -->
  • <!-- @include: filename{start-} -->
  • <!-- @include: filename{-end} -->

Also, you can include file region:

  • <!-- @include: filename#region -->

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>

Demo

<!-- @include: ./demo.snippet.md -->:

Heading 2

Contents containing bolded text and some markdown enhance features:

Tips

Hey how are you? 😄

<!-- @include: ./demo.snippet.md{9-13} -->:

Tips

Hey how are you? 😄

<!-- @include: ./demo.snippet.md#snippet -->:

Contents containing bolded text and some markdown enhance features:

Advanced

You can also set an object to customize include filepath and include behavior.

interface IncludeOptions {
  /**
   * handle include filePath
   *
   * @default (path) => path
   */
  resolvePath?: (path: string, cwd: string | null) => string;
  /**
   * Whether deep include files in included Markdown files
   *
   * @default false
   */
  deep?: boolean;
  /**
   * Whether use `<!-- @include: xxx -->` instead of `@include: xxx` to include files
   *
   * @default true
   */
  useComment?: boolean;
  /**
   * Whether resolve the image related path in the included Markdown file
   *
   * @default true
   */
  resolveImagePath?: boolean;
  /**
   * Whether resolve the related file link path in the included Markdown file
   *
   * @default true
   */
  resolveLinkPath?: boolean;
}

E.g.: you can use @src as an alias for your source directory.

TS
import { getDirname, path } from "vuepress/utils";
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

const __dirname = getDirname(import.meta.url);

export default defineUserConfig({
  theme: hopeTheme({
    plugins: {
      mdEnhance: {
        // Add `@src` alias support
        include: {
          resolvePath: (file) => {
            if (file.startsWith("@src"))
              return file.replace("@src", path.resolve(__dirname, ".."));

            return file;
          },
        },
      },
    },
  }),
});












 
 
 
 
 
 
 
 



Also, to place your Markdown files directly besides your actual files, but don't want them rendered as pages, you can set pagePatterns options in VuePress config. See pagePatternsopen in new window for more details.

TS
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  // now any file with `.snippet.md` extension will not be rendered as a page
  pagePatterns: ["**/*.md", "!**/*.snippet.md", "!.vuepress", "!node_modules"],

  theme: hopeTheme({
    plugins: {
      mdEnhance: {
        include: true,
      },
    },
  }),
});