Node API

@vuepress/core

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:
ParameterTypeDescription
configAppConfigConfig 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)
}

createDevApp

  • Signature:
const createDevApp: (config: AppConfig) => DevApp
  • Parameters:
ParameterTypeDescription
configAppConfigConfig 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)
}

App Properties

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.

siteData

  • Type: SiteData

  • Details:

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

version

  • Type: string

  • Details:

    Version of VuePress app, i.e. version of @vuepress/core package.

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.

markdown

pages

  • Type: Page[]

  • Details:

    The Page object array.

    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')

writeTemp

  • Signature:
writeTemp(file: string, content: string): Promise<string>
  • Parameters:
ParameterTypeDescription
filestringFilepath of the temp file that going to be wrote. Relative to temp directory.
contentstringContent 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:

export default  {
  // write temp file in onPrepared hook
  async onPrepared() {
    await app.writeTemp('foo.js', 'export const foo = \'bar\'')
  }
}
// import temp file in client code
import { foo } from '@temp/foo'

init

  • Signature:
init(): Promise<void>

prepare

  • Signature:
prepare(): Promise<void>

build

  • Signature:
build(): Promise<void>

dev

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

Page

createPage

  • Signature:
const createPage: (app: App, options: PageOptions) => Promise<Page>
  • Parameters:
ParameterTypeDescription
appAppThe VuePress app instance.
optionsPageOptionsOptions to create VuePress page.
  • Details:

    Create a VuePress page object.

  • Example:

import { createPage } from '@vuepress/core'

export default  {
  // 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.
`,
      })
    )
  },
}

Page Properties

key

path

title

lang

  • Type: string

  • Details:

    Language of the page.

  • Example:

    • 'en-US'
    • 'zh-CN'
  • Also see:

frontmatter

  • Type: PageFrontmatter

  • Details:

    Frontmatter of the page.

  • Also see:

excerpt

  • Type: string

  • Details:

    Excerpt of the page.

    If a Markdown file contains a <!-- more --> 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.

headers

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

data

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

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:

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:

  • Type: MarkdownLink[]
interface MarkdownLink {
  raw: string
  relative: string
  absolute: string
}
  • 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:

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:

routeMeta

What's the difference between route meta and page data?

Both route meta and page data is available in client side. However, route meta is attached to the route record, so the route meta of all pages would be loaded at once when users enter your site. In the contrast, page data is saved in separated files, which would be loaded only when users enter the corresponding page.

Therefore, it's not recommended to store large amounts of info into route meta, otherwise the initial loading speed will be affected a lot when your site has a large number of pages.

sfcBlocks

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.