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)
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- Also see:
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)
}
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:
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.
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 directorydir.temp()
: resolve to temp directorydir.source()
: resolve to source directorydir.dest()
: resolve to dest directorydir.client()
: resolve to@vuepress/client
directorydir.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')
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\'')
}
}
2
3
4
5
6
// import temp file in client code
import { foo } from '@temp/foo'
2
init
- Signature:
init(): Promise<void>
Details:
Initialize VuePress app.
Also see:
prepare
- Signature:
prepare(): Promise<void>
Details:
Prepare client temp files.
Also see:
build
- Signature:
build(): Promise<void>
Details:
Generate static site files.
This method is only available in
BuildApp
.Also see:
dev
- Signature:
dev(): Promise<() => Promise<void>>
Details:
Start dev server.
This method is only available in
DevApp
.Also see:
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.
`,
})
)
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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:
path
Type:
string
Details:
Route path of the page.
Also see:
title
Type:
string
Details:
Title of the page.
Also see:
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.
2
3
4
5
6
7
headers
- Type:
PageHeader[]
interface PageHeader {
level: number
title: string
slug: string
children: PageHeader[]
}
2
3
4
5
6
Details:
Headers of the page.
Also see:
data
- Type:
PageData
interface PageData {
key: string
path: string
title: string
lang: string
frontmatter: PageFrontmatter
excerpt: string
headers: PageHeader[]
}
2
3
4
5
6
7
8
9
Details:
Data of the page.
Page data would be available in client side.
Also see:
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:
hoistedTags
Type:
string[]
Details:
Hoisted tags of the page.
Also see:
links
- Type:
MarkdownLink[]
interface MarkdownLink {
raw: string
relative: string
absolute: string
}
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:
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:
permalink
Type:
string | null
Details:
Permalink of the page.
Also see:
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.