Node API

@vuepress/core

Node API 是由 @vuepress/core在新窗口打开 包提供的。它是 vuepress在新窗口打开 包的依赖之一,当然你也可以单独安装它:

npm i -D @vuepress/core@next

App

插件 API 的所有 Hooks 中都可以获取到 App 实例。

BuildAppDevApp 除了 builddev 方法外,拥有一样的属性和方法。

createBuildApp

  • 函数签名:
const createBuildApp: (config: AppConfig) => BuildApp
  • 参数:
参数类型描述
configAppConfig创建 VuePress App 的选项。
  • 详情:

    创建一个 Build 模式的 App 实例,用于构建静态文件。

  • 示例:

const build = async () => {
  const app = createBuildApp({
    // ...配置项
  })

  // 初始化和准备
  await app.init()
  await app.prepare()

  // 构建
  await app.build()

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

createDevApp

  • 函数签名:
const createDevApp: (config: AppConfig) => DevApp
  • 参数:
参数类型描述
configAppConfig创建 VuePress App 的选项。
  • 详情:

    创建一个 Dev 模式的 App 实例,用于启动开发服务器。

  • 示例:

const dev = async () => {
  const app = createDevApp({
    // ...配置项
  })

  // 初始化和准备
  await app.init()
  await app.prepare()

  // 启动开发服务器
  const closeDevServer = await app.dev()

  // 准备文件监听器
  const watchers = []

  // 重启开发服务器
  const restart = async () => {
    await Promise.all([
      // 关闭所有监听器
      ...watchers.map((item) => item.close()),
      // 关闭当前的开发服务器
      closeDevServer(),
    ])
    await dev()
  }

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

App 属性

options

  • 类型: AppOptions

  • 详情:

    VuePress App 的配置项。

    这些配置项来自于 createBuildApp / createDevAppconfig 参数,但所有可选的字段都填充上了默认值。

siteData

  • 类型: SiteData

  • 详情:

    由用户设置的站点数据,包含所有的 站点配置 ,可以在客户端代码中使用。

version

  • 类型: string

  • 详情:

    VuePress App 的版本,即 @vuepress/core 包的版本。

env.isBuild

  • 类型: boolean

  • 详情:

    用于判断 App 是否运行在 Build 模式的环境标记,即当前 App 是否是 BuildApp 实例。

env.isDev

  • 类型: boolean

  • 详情:

    用于判断 App 是否运行在 Dev 模式的环境标记,即当前 App 是否是 DevApp 实例。

env.isDebug

  • 类型: boolean

  • 详情:

    用于判断 App 是否开启 Debug 模式的环境标记。

markdown

layouts

  • 类型: Record<string, string>

  • 详情:

    布局组件 Map ,其键为布局名称,对应值为布局组件的绝对文件路径。

    它仅在 onInitialized 以及之后的 Hooks 中才可用。

pages

  • 类型: Page[]

  • 详情:

    Page 对象数组。

    它仅在 onInitialized 以及之后的 Hooks 中才可用。

App 方法

dir

  • 工具函数:

    • dir.cache(): 解析至缓存目录
    • dir.temp(): 解析至临时文件目录
    • dir.source(): 解析至源文件目录
    • dir.dest(): 解析至输出目录
    • dir.client(): 解析至 @vuepress/client 目录
    • dir.public(): 解析至 Public 文件目录
  • 函数签名:

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

    用于解析对应目录下的文件绝对路径的一些工具函数。

    如果你不传入任何参数,就会返回对应目录的绝对路径。

  • 示例:

// 解析 `${sourceDir}/README.md` 文件的绝对路径
const homeSourceFile = app.dir.source('README.md')

writeTemp

  • 函数签名:
writeTemp(file: string, content: string): Promise<string>
  • 参数:
参数类型描述
filestring要写入的临时文件的路径,相对于临时文件目录。
contentstring要写入的临时文件路径的内容。
  • 详情:

    用于写入临时文件的方法。

    写入的文件可以在客户端文件中通过 @temp 别名来引入。

  • 示例:

export default {
  // 在 onPrepared hook 中写入临时文件
  async onPrepared() {
    await app.writeTemp('foo.js', 'export const foo = \'bar\'')
  }
}
// 在客户端文件中引入临时文件
import { foo } from '@temp/foo'

init

  • 函数签名:
init(): Promise<void>

prepare

  • 函数签名:
prepare(): Promise<void>

build

  • 函数签名:
build(): Promise<void>

dev

  • 函数签名:
dev(): Promise<() => Promise<void>>

Page

createPage

  • 函数签名:
const createPage: (app: App, options: PageOptions) => Promise<Page>
  • 参数:
参数类型描述
appAppVuePress App 实例。
optionsPageOptions创建 VuePress Page 的选项。
  • 详情:

    创建一个 VuePress Page 对象。

  • 示例:

import { createPage } from '@vuepress/core'

export default {
  // 在 onInitialized hook 中创建一个额外页面
  async onInitialized(app) {
    app.pages.push(
      await createPage(app, {
        path: '/foo.html',
        frontmatter: {
          layout: 'Layout',
        },
        content: `\
# 某个 Page

你好,世界。
`,
      })
    )
  },
}

Page 属性

key

path

title

lang

  • 类型: string

  • 详情:

    该 Page 的语言。

  • 示例:

    • 'en-US'
    • 'zh-CN'
  • 参考:

frontmatter

  • 类型: PageFrontmatter

  • 详情:

    该 Page 的 Frontmatter 。

  • 参考:

excerpt

  • 类型: string

  • 详情:

    该 Page 的摘要。

    如果一个 Markdown 文件中包含一个 <!-- more --> 注释,那么该注释上方的内容都会被作为摘要提取并渲染。

    如果你在创建一个用于博客的自定义主题,那么它可以帮助你创建一个包含摘要的文章列表。

  • 示例:

`<!-- more -->` 注释上方的内容会被当作摘要。

建议你在该注释前后添加空行,以避免渲染问题。

<!-- more -->

`<!-- more -->` 注释下方的内容不会被当作摘要。

headers

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

data

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

content

  • 类型: string

  • 详情:

    该 Page 的未经渲染的原始内容。

contentRendered

  • 类型: string

  • 详情:

    该 Page 的渲染后的内容。

date

  • 类型: string

  • 详情:

    该 Page 的日期,遵从 'yyyy-MM-dd' 格式。

  • 示例:

    • '0000-00-00'
    • '2021-08-16'
  • 参考:

deps

  • 类型: string[]

  • 详情:

    该 Page 的依赖。

    举例来说,如果在页面中导入了代码片段,那么被导入文件的绝对路径就会被添加到 deps 中。

  • 参考:

  • 类型: MarkdownLink[]
interface MarkdownLink {
  raw: string
  relative: string
  absolute: string
}
  • 详情:

    该 Page 中的链接。

pathInferred

  • 类型: string | null

  • 详情:

    该 Page 根据文件路径推断出的路由路径。

    默认情况下,路由路径是根据 Markdown 源文件的相对文件路径推断出来的。然而,用户可能会显式指定页面路由,比如通过 permalink 来指定该页面最终使用的路由路径。因此我们在 Page 属性中保留推断出来的路径,以便于你在某些情况下可能会用到它。

    如果该 Page 不是来自于 Markdown 源文件,那么该属性会为 null

  • 示例:

    • '/'
    • '/foo.html'
  • 参考:

pathLocale

  • 类型: string

  • 详情:

    该 Page 路由路径的 Locale 前缀。

    它是根据页面的 Markdown 源文件相对路径、以及用户配置的 locales 的键推断得到的。

  • 示例:

    • '/'
    • '/en/'
    • '/zh/'
  • 参考:

routeMeta

Route Meta 和 Page Data 的区别是什么?

Route MetaPage Data 都可以在客户端代码中使用。然而, Route Meta 是附加在路由记录上的,因此当用户进入你的站点时,所有页面的 Route Meta 都会立即被加载。相比之下, Page Data 是存储在单独的文件中的,只有在用户进入对应页面时才会被加载。

因此,不建议在 Route Meta 中存储大量的信息,否则在站点有很多页面时,将会影响站点的初始加载速度。

sfcBlocks

  • 类型: MarkdownSfcBlocks

  • 详情:

    该 Page 中提取出的 Vue SFC Blocks 。

  • 参考:

slug

  • 类型: string

  • 详情:

    该 Page 的 Slug 。

    它是根据页面的 Markdown 源文件的文件名推断得到的。

filePath

  • 类型: string | null

  • 详情:

    该 Page 的 Markdown 源文件的绝对路径。

    如果该 Page 不是来自于 Markdown 源文件,那么该属性会为 null

filePathRelative

  • 类型: string | null

  • 详情:

    该 Page 的 Markdown 源文件的相对路径。

    如果该 Page 不是来自于 Markdown 源文件,那么该属性会为 null