乐趣区

关于前端:Vitepress-的实现原理

jiezi

什么是 Vitepress？

Vitepress 是由 Vite 和 Vue 驱动的动态站点生成器，通过获取 Markdown 编写的内容，并能够生成对应的动态 HTML 页面。咱们常常应用 Vitepress 构建博客等动态网站，本文次要解析一下 Vitepress 的实现原理，上面就开始吧！

原理

初始化我的项目

依据官网文档举荐，咱们执行以下命令初始化我的项目：

npx vitepress init

执行完命令便会进入一个设置界面，通过设置我的项目名等参数，最终生成一个 vitepress 我的项目。

咱们都晓得，npx vitepress init 实际上等同于：

npm i -g vitepress
vitepress init

很好了解，先全局装置 vitepress，再执行 vitepress init 命令：

先通过 @clack/prompts 开启命令行 UI 界面，用户进行初始化配置：

// src/node/init/init.ts
import {group} from '@clack/prompts'

const options: ScaffoldOptions = await group(
    {root: () =>
        text({
          message: 'Where should VitePress initialize the config?',
          initialValue: './',
          validate(value) {// TODO make sure directory is inside}
        }),
    
      title: () =>
        text({
          message: 'Site title:',
          placeholder: 'My Awesome Project'
        }),
    // ... 以下省略
)

再依据配置项从 template 文件夹中拉取模板文件，实现我的项目的初始化。

启动服务

在 Vitepress 我的项目中，咱们通过执行以下命令启动文档服务：

vitepress dev

执行完命令，咱们便能够在浏览器拜访文档网站！

启动服务次要分为两步：

  1. 创立 Vite 服务；
  2. 执行 Vite 插件；

创立 Vite 服务 

// src/node/server.ts
import {createServer as createViteServer, type ServerOptions} from 'vite'
import {resolveConfig} from './config'
import {createVitePressPlugin} from './plugin'

export async function createServer(root: string = process.cwd(),
  serverOptions: ServerOptions & {base?: string} = {},
  recreateServer?: () => Promise<void>) {
  // 读取 vitepress 配置
  const config = await resolveConfig(root)

  if (serverOptions.base) {
    config.site.base = serverOptions.base
    delete serverOptions.base
  }

  // 创立 vite 服务
  return createViteServer({
    root: config.srcDir,
    base: config.site.base,
    cacheDir: config.cacheDir,
    plugins: await createVitePressPlugin(config, false, {}, {}, recreateServer),
    server: serverOptions,
    customLogger: config.logger,
    configFile: config.vite?.configFile
  })
}

上述代码创立并启动了一个 Vite 服务：首先，通过调用 resolveConfig，读取用户的 Vitepress 配置并整合为一个 config 对象（配置门路默认为：.vitepress/config/index.js），再将局部配置传入 createViteServer，创立并启动 Vite 服务。

执行 Vite 插件

看完下面的内容，你可能会有点纳闷，失常来说，Vite 须要一个 HTML 作为入口文件，但咱们找遍 Vitepress 也未发现咱们想要的 HTML 文件……其实这部分工作由 Vite 插件实现，在下面的代码片段中，咱们创立了 Vite 服务，同时配置了插件：

// src/node/server.ts
return createViteServer({
    // 省略代码
    plugins: await createVitePressPlugin(config, false, {}, {}, recreateServer),
    // 省略代码
})

createVitePressPlugin 函数返回了一个插件列表，其中有一个名为 vitepress 的插件：

// src/node/plugin.ts
const vitePressPlugin: Plugin = {
    name: 'vitepress',
    // 省略代码
    configureServer(server) {
      // 省略代码
      return () => {server.middlewares.use(async (req, res, next) => {const url = req.url && cleanUrl(req.url)
          if (url?.endsWith('.html')) {
            res.statusCode = 200
            res.setHeader('Content-Type', 'text/html')
            let html = `<!DOCTYPE html>
<html>
  <head>
    <title></title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <meta name="description" content="">
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/@fs/${APP_PATH}/index.js"></script>
  </body>
</html>`
            html = await server.transformIndexHtml(url, html, req.originalUrl)
            res.end(html)
            return
          }
          next()})
      }
    },
    // 省略代码
  }

vitepress 插件中定义了 configureServer 生命周期，并在 configureServer 中返回一个 HTML 文件，作为 Vite 服务的入口 HTML 文件，当咱们拜访服务时，浏览器渲染网页，执行 HTML 中引入的 Script 文件（<script type="module" src="/@fs/${APP_PATH}/index.js"></script>，其中 APP_PATH 为 src/client/app/index.ts），网页失常展现在咱们眼前，至此，服务失常启动！

文档渲染

在下面的局部，咱们整顿了启动服务的大抵步骤，接下来咱们将接着整顿 Markdown 文件和路由的映射关系！

创立路由

Vitepress 并没有应用 Vuejs 的官网路由计划（Vue Router），而是本人实现了一个简略的路由模块：首先通过监听 window 的点击事件，当用户点击超链接元素时，执行跳转函数 go：

// src/client/app/router.ts
async function go(href: string = inBrowser ? location.href : '/') {href = normalizeHref(href)
    if ((await router.onBeforeRouteChange?.(href)) === false) return
    updateHistory(href)
    await loadPage(href)
    await router.onAfterRouteChanged?.(href)
}

function updateHistory(href: string) {if (inBrowser && normalizeHref(href) !== normalizeHref(location.href)) {
        // save scroll position before changing url
        history.replaceState({scrollPosition: window.scrollY}, document.title)
        history.pushState(null, '', href)
    }
}

通过执行 updateHistory，先调用 history.replaceState，将以后页面的地位信息 scrollY 保留到 history state 中；再调用 history.pushState，更新 url；最初再调用 loadPage 加载 url 对应的页面，外围代码如下：

// src/client/app.ts
let pageFilePath = pathToFile(path)
let pageModule = null
// 省略代码
pageModule = import(/*@vite-ignore*/ pageFilePath + '?t=' + Date.now())
// 省略代码
return pageModule

pathToFile 函数将传入的 url 转成 md 后缀的门路，也就是对应的 Markdown 文件，再通过 import 导入对应门路的文件；举个例子，假如 url 为 /ruofee，那么最终后果为：import(/*@vite-ignore*/ 'ruofee.md?t= 以后的工夫戳')；

同时监听 popstate 事件，当用户应用浏览器返回、后退等操作时，调用 loadPage 办法，加载 url 对应的 md 文件，并依据 history state 中保留的页面地位信息进行定位：

// src/client/app/router.ts
window.addEventListener('popstate', async (e) => {
    await loadPage(normalizeHref(location.href),
        (e.state && e.state.scrollPosition) || 0
    )
    router.onAfterRouteChanged?.(location.href)
})

// 省略代码 - loadPage
window.scrollTo(0, scrollPosition)

创立 Vue 利用 

// src/client/app.ts
import {
  createApp,
  type App
} from 'vue'

// 省略代码
function newApp(): App {
    // 省略代码
    return createApp(VitePressApp)
}

const app = newApp()

首先通过执行 createApp(VitePressApp) 创立 Vue 利用，VitePressApp 是以后主题的 Layout 组件（@theme 是别名配置，指向以后主题，若是没有设置，则默认为 src/client/theme-default）：

// src/client/app.ts
import RawTheme from '@theme/index'

const Theme = resolveThemeExtends(RawTheme)

const VitePressApp = defineComponent({
    name: 'VitePressApp',
    setup() {
    // 省略代码
        return () => h(Theme.Layout!)
    }
})

再将下面的路由对象注册到 Vue 利用中，并注册两个全局组件：Content 和 ClientOnly：

// src/client/app.ts
// 将路由注入 app
app.provide(RouterSymbol, router)
const data = initData(router.route)
app.provide(dataSymbol, data)

// 注册全局组件
app.component('Content', Content)
app.component('ClientOnly', ClientOnly)

Markdown 渲染

直到目前为止，咱们曾经启动了 Vite 服务，咱们能够在浏览器中拜访 HTML，并执行 Script 创立 Vue 利用，实现了路由零碎，当咱们拜访对应链接时，便会加载对应的 Markdown 文件，但你必定会有纳闷：咱们的 Markdown 文件如何被解析渲染到页面中呢？

其实在启动服务的局部中，咱们提到了一个名为 vitepress 的 vite 插件，Markdown 渲染工作便是在这个插件的 transform 生命周期中实现：

// src/node/plugin.ts
{async transform(code, id) {if (id.endsWith('.vue')) {return processClientJS(code, id)
        } else if (id.endsWith('.md')) {
            // transform .md files into vueSrc so plugin-vue can handle it
            const {vueSrc, deadLinks, includes} = await markdownToVue(
              code,
              id,
              config.publicDir
            )
            // 省略代码
            const res = processClientJS(vueSrc, id)
            return res
        }
    }
}

当咱们应用 import 加载 md 文件时，便会调用 transform 函数，对文件内容进行转换：执行 markdownToVue，将 markdown 内容转成 Vue SFC，再通过 @vitejs/plugin-vue 插件将 Vue 组件渲染到页面；那么 markdownToVue 做了什么工作呢？具体如下：

// src/node/markdownToVue.ts
const html = md.render(src, env)
const vueSrc = [
    // 省略代码
    `<template><div>${html}</div></template>`,
    // 省略代码
].join('\n')

这部分比较简单，md 是一个 markdown-it 对象，通过调用 md.render 函数，将 markdown 内容转成 HTML 格局，再输入到页面；

值得一提的是，若是你在 markdown 中书写 Vue 组件语法，因为是非 markdown 语法，因而 markdown-it 不会对其进行转换，那么 Vue 语法将在页面中得以执行，官网中的例子便是利用这个原理！

总结

以上便是 Vitepress 大抵的原理，Vitepress 是一个十分优良的文档构建工具，其中有很多设计上的细节文章没提到，具体大家能够自行去 Github 上查看源码！

退出移动版