vitepress

前言

现在Vuepress的环境已经非常完善，有很多配套的主题、插件等。但是 Vue3 + Vite 对于前端来说，不仅功能多，还快，所以在有了 vuepress 的经验之后，最近开始着手使用vitepress。

1、搭建 vitepress

搭建项目的步骤同官网

//1.创建一个空项目
mkdir vitepress-blog && cd vitepress-blog

//2.初始化，可以使用你自己喜欢的包管理器
yarn init

//3.添加vitepress和vue依赖
yarn add --dev vitepress vue

//4.创建一个文档
mkdir docs && echo '# Hello VitePress' > docs/index.md

//5.在package.json中添加脚本
{
  ...
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "serve": "vitepress serve docs"
  },
  ...
}

//6.运行
yarn dev

2、配置

在没有任何配置的情况下，这只是个非常简单的页面。
要自定义首先在docs目录中创建.vitepress目录
配置VitePress的基本文件是.vitepress/config.js，它应该导出一个 JavaScript 对象：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json

// config.js
export default {
  title: 'VitePress',
  description: 'Just playing around.',
}

我的配置

const nav = require('./nav.js')
const sidebar = require('./sidebar.js')
module.exports = {
  title: 'Yeungtg',
  description: 'Yeungtg blog',
  author: 'Yeungtg',
  appearance: true,
  lang: 'zh-CN',
  // 从 URL 中删除随尾.html
  cleanUrls: 'with-subfolders',
  markdown: {
    //显示代码行数
    lineNumbers: true,
  },
  //以git提交的时间为更新时间
  lastUpdated: true,
  themeConfig: {
    logo: '/logo.svg',
    docFooter: {
      //上下篇文本
      prev: '上一篇',
      next: '下一篇',
    },
    author: 'Yeungtg',
    //最后更新时间文本
    lastUpdatedText: '上次更新时间',
    nav,
    sidebar,
  },
}

3、自定义首页

Vitepress可以通过将 layout 选项设置为页面 frontmatter 来选择页面布局。
有doc、page、home布局选项，如果未指定任何内容，则该页面被视为doc页面

:::tip 官方标准配置

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress
---

:::

:::warning 在Vitepress中，每个markdown文件中都可以使用Vue功能，包括动态模板、组件等
:::

1、新建组件

// docs/components/home.vue
<template>
  <section class="home">
    {{ num }}
  </section>
</template>
<script setup>
import { ref } from 'vue'
const num = ref(7)
</script>
<style lang="scss" scoped>
.home {
  background: #ccc;
}
</style>

2、重写首页

:::tip 组件中可能会有用到本地资源的时候，资源文件都放在 docs/public 下面，引用时直接/资源即可
:::

// docs/index.md
---
layout: home
---

<script setup>
import home from './components/home.vue'
</script>

<home />

4、自定义文档

1、新增文件

在themem新增Layout.vue、index.js文件，目录如下

.
├─ docs
│  ├─ .vitepress
│  │  └─ theme
│  │     ├─ index.js
│  │     └─ layout.vue
│  └─ index.md
└─ package.json

新增index.js

// .vitepress/theme/index.js
import Layout from './layout.vue'
import DefaultTheme from 'vitepress/theme' //viteperss的主题

export default {
  ...DefaultTheme,
  Layout,

  enhanceApp({ app, router, siteData }) {
    // app is the Vue 3 app instance from `createApp()`.
    // router is VitePress' custom router. `siteData` is
    // a `ref` of current site-level metadata.
  },
  setup() {
    // this function will be executed inside VitePressApp's
    // setup hook. all composition APIs are available here.
  }
}

新增 Layout.vue

::: details VitePress 提供了一些 API 给我们去获取应用的数据。

interface VitePressData {
  site: Ref<SiteData>
  page: Ref<PageData>
  theme: Ref<any> // themeConfig from .vitepress/config.js
  frontmatter: Ref<PageData['frontmatter']>
  lang: Ref<string>
  title: Ref<string>
  description: Ref<string>
  localePath: Ref<string>
}

:::

<!--.vitepress/theme/layout.vue-->
<script setup>
import DefaultTheme from 'vitepress/theme'
import { useData } from 'vitepress'
const { Layout } = DefaultTheme
//这里的frontmatter就是各个md文件中自己写在最上面的东西
const { frontmatter, theme, page } = useData()
</script>

<template>
  <Layout>
    <template #doc-before>
      <h1 class="page-title">
        <span></span>
        <p>{{ frontmatter.title }}</p>
      </h1>
      <span class="page-info">{{ frontmatter.author }}</span>
      <span class="page-info">{{ frontmatter.date }}</span>
    </template>
  </Layout>
</template>

<style lang="scss">
.page-title {
  font-size: 26px;
  color: var(--vp-c-text-1);
  font-weight: bold;
  margin-bottom: 30px;
}
.page-info {
  font-size: 13px;
  color: #7f7f7f;
  margin-right: 10px;
}
</style>

::: tip Vitepress 提供了很多页面上的插槽，方便我们使用，例如：

<template #aside-bottom>
  <button class="page-to-top">返回顶部</button>
</template>

:::

结论

本文是一个 Vitepress 的大概搭建流程，viteperss还在持续更新，请持续关注官网变更。