Node API

Node API is provided by @vuepress/coreopen in new window package. It is a dependency of the vuepressopen in new window package, and you can also install it separately:

npm i -D @vuepress/core@next

App

The app instance is available in all hooks of Plugin API.

The BuildApp and DevApp share almost the same properties and methods, except build and dev method.

createBuildApp

Signature:

const createBuildApp: (config: AppConfig) => BuildApp;

Parameters:

Parameter	Type	Description
config	`AppConfig`	Config to create a VuePress app.

Details:
Create a build mode app instance, which is used for building static files.
Example:

const build = async () => {
  const app = createBuildApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // build
  await app.build()

  // process onGenerated hook
  await app.pluginApi.hooks.onGenerated.process(app)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Also see:
- Node API > App Methods > build

createDevApp

Signature:

const createDevApp: (config: AppConfig) => DevApp

Parameters:

Parameter	Type	Description
config	`AppConfig`	Config to create a VuePress app.

Details:
Create a dev mode app instance, which is used for starting a dev server.
Example:

const dev = async () => {
  const app = createDevApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // start dev server
  const closeDevServer = await app.dev()

  // set up file watchers
  const watchers = []

  // restart dev server
  const restart = async () => {
    await Promise.all([
      // close all watchers
      ...watchers.map((item) => item.close()),
      // close current dev server
      closeDevServer(),
    ])
    await dev()
  }

  // process onWatched hook
  await app.pluginApi.hooks.onWatched.process(app, watchers, restart)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

Also see:
- Node API > App Methods > dev

App Properties

version

Type: string
Details:
Version of VuePress app, i.e. version of @vuepress/core package.

options

Type: AppOptions
Details:
Options of VuePress app.
The options come from the config argument in createBuildApp / createDevApp, while all optional fields will be filled with a default value.

env.isBuild

Type: boolean
Details:
Environment flag used to identify whether the app is running in build mode, i.e. whether a BuildApp instance.

env.isDev

Type: boolean
Details:
Environment flag used to identify whether the app is running in dev mode, i.e. whether a DevApp instance.

env.isDebug

Type: boolean
Details:
Environment flag used to identify whether the debug mode is enabled.

siteData

Type: SiteData
Details:
Site data that set by user, including all the site config, which will be used in client side.

markdown

Type: MarkdownIt
Details:
The markdown-itopen in new window instance used for parsing markdown content.

layouts

Type: Record<string, string>
Details:
The layout components map, of which the key is the layout name, the value is the absolute file path of the layout component.
It is only available in and after onInitialized hook.

App Methods

dir

Utils:
- dir.cache(): resolve to cache directory
- dir.temp(): resolve to temp directory
- dir.source(): resolve to source directory
- dir.dest(): resolve to dest directory
- dir.client(): resolve to @vuepress/client directory
- dir.public(): resolve to public directory
Signature:

type AppDirFunction = (...args: string[]) => string

Details:
Utils to resolve the absolute file path in corresponding directory.
If you don't provide any arguments, it will return the absolute path of the directory.
Example:

// resolve the absolute file path of the `${sourceDir}/README.md`
const homeSourceFile = app.dir.source('README.md')

1
2

writeTemp

Signature:

writeTemp(file: string, content: string): Promise<string>

Parameters:

Parameter	Type	Description
file	`string`	Filepath of the temp file that going to be wrote. Relative to temp directory.
content	`string`	Content of the temp file that going to be wrote.

Details:
A method to write temp file.
The written file could be imported via @temp alias in client files.
Example:

module.exports = {
  // write temp file in onPrepared hook
  async onPrepared() {
    await app.writeTemp('foo.js', 'export const foo = \'bar\'')
  }
}

1
2
3
4
5
6

// import temp file in client code
import { foo } from '@temp/foo'

1
2

init

Signature:

init(): Promise<void>

Details:
Initialize VuePress app.
Also see:
- Advanced > Architecture > Core Process and Hooks

prepare

Signature:

prepare(): Promise<void>

Details:
Prepare client temp files.
Also see:
- Advanced > Architecture > Core Process and Hooks

build

Signature:

build(): Promise<void>

Details:
Generate static site files.
This method is only available in BuildApp.
Also see:
- Node API > App > createBuildApp
- Advanced > Architecture > Core Process and Hooks

dev

Signature:

dev(): Promise<() => Promise<void>>

Details:
Start dev server.
This method is only available in DevApp.
Also see:
- Node API > App > createDevApp
- Advanced > Architecture > Core Process and Hooks

Page

createPage

Signature:

const createPage: (app: App, options: PageOptions) => Promise<Page>

Parameters:

Parameter	Type	Description
app	`App`	The VuePress app instance.
options	`PageOptions`	Options to create VuePress page.

Details:
Create a VuePress page object.
Example:

const { createPage } = require('@vuepress/core')

module.exports = {
  // create an extra page in onInitialized hook
  async onInitialized(app) {
    app.pages.push(
      await createPage(app, {
        path: '/foo.html',
        frontmatter: {
          layout: 'Layout',
        },
        content: `\
# Foo Page

Hello, world.
`,
      })
    )
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Also see:
- Node API > App Properties > pages
- Cookbook > Adding Extra Pages

Page Properties

key

Type: string
Details:
Identifier of the page.
The page key would be used as the nameopen in new window of the page route.
Also see:
- Built-in Components > Content

path

Type: string
Details:
Route path of the page.
Also see:
- Guide > Page > Routing
- Node API > Page Properties > pathInferred

title

Type: string
Details:
Title of the page.
Also see:
- Frontmatter > title

lang

Type: string
Details:
Language of the page.
Example:
- 'en-US'
- 'zh-CN'
Also see:
- Frontmatter > lang

frontmatter

Type: PageFrontmatter
Details:
Frontmatter of the page.
Also see:
- Frontmatter

excerpt

Type: string
Details:
Excerpt of the page.
If a Markdown file contains a  comment, any content above the comment will be extracted and rendered as excerpt.
If you are building a custom theme for blogging, it would be helpful to generate a post list with excerpts.
Example:

Lines above `<!-- more -->` comment would be used as excerpt.

It's recommended to wrap the comment with empty lines to avoid rendering issue.

<!-- more -->

Lines below `<!-- more -->` comment would not be used as excerpt.

1
2
3
4
5
6
7

headers

Type: PageHeader[]

interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}

1
2
3
4
5
6

Details:
Headers of the page.
Also see:
- Config > markdown.extractHeaders

data

Type: PageData

interface PageData {
  key: string
  path: string
  title: string
  lang: string
  frontmatter: PageFrontmatter
  excerpt: string
  headers: PageHeader[]
}

1
2
3
4
5
6
7
8
9

Details:
Data of the page.
Page data would be available in client side.
Also see:
- Client API > usePageData
- Plugin API > extendsPageData

content

Type: string
Details:
Raw content of the page.

contentRendered

Type: string
Details:
Rendered content of the page.

date

Type: string
Details:
Date of the page, in 'yyyy-MM-dd' format.
Example:
- '0000-00-00'
- '2021-08-16'
Also see:
- Frontmatter > date

deps

Type: string[]
Details:
Dependencies of the page.
For example, if users import code snippet in the page, the absolute file path of the imported file would be added to deps.
Also see:
- Config > markdown.importCode

hoistedTags

Type: string[]
Details:
Hoisted tags of the page.
Also see:
- Config > markdown.hoistTags

links

Type: MarkdownLink[]

interface MarkdownLink {
  raw: string
  relative: string
  absolute: string
}

1
2
3
4
5

Details:
Links of the page.

pathInferred

Type: string | null
Details:
Route path of the page that inferred from file path.
By default, the route path is inferred from the relative file path of the Markdown source file. However, users may explicitly set the route path, e.g. permalink, which would be used as the final route path of the page. So we keep the inferred path as a page property in case you may need it.
It would be null if the page does not come from a Markdown source file.
Example:
- '/'
- '/foo.html'
Also see:
- Guide > Page > Routing
- Node API > Page Properties > path

pathLocale

Type: string
Details:
Locale prefix of the page route path.
It is inferred from the relative file path of the Markdown source file and the key of locales option in user config.
Example:
- '/'
- '/en/'
- '/zh/'
Also see:
- Config > locales

permalink

Type: string | null
Details:
Permalink of the page.
Also see:
- Frontmatter > permalink
- Frontmatter > permalinkPattern

slug

Type: string
Details:
Slug of the page.
It is inferred from the filename of the Markdown source file.

filePath

Type: string | null
Details:
Absolute path of the Markdown source file of the page.
It would be null if the page does not come from a Markdown source file.

filePathRelative

Type: string | null
Details:
Relative path of the Markdown source file of the page.
It would be null if the page does not come from a Markdown source file.

# Node API

# App

# createBuildApp

# createDevApp

# App Properties

# version

# options

# env.isBuild

# env.isDev

# env.isDebug

# siteData

# markdown

# layouts

# pages

# App Methods

# dir

# writeTemp

# init

# prepare

# build

# dev

# Page

# createPage

# Page Properties

# key

# path

# title

# lang

# frontmatter

# excerpt

# headers

# data

# content

# contentRendered

# date

# deps

# hoistedTags

# links

# pathInferred

# pathLocale

# permalink

# slug

# filePath

# filePathRelative