用途
搭建自己的markdown阅读网站；可以自定义开发，提供了底层的markdown文档编辑器
项目搭建
创建项目
$ npx vitepress init
初始化使用默认配置即可；
运行项目
# 安装依赖
pnpm install vitepress vue
# 运行项目
pnpm docs:dev
编写markdown文件并添加到列表中
首先我们来看.vitepress/config.mts中的内容
import { defineConfig } from 'vitepress'
// <https://vitepress.dev/reference/site-config>
export default defineConfig({
title: "My Awesome Project",
description: "A VitePress Site",
themeConfig: { // 主题方案配置
// <https://vitepress.dev/reference/default-theme-config>
nav: [// 菜单栏
{ text: 'Home', link: '/' },
{ text: 'Examples', link: '/markdown-examples' }
],
sidebar: [ // 侧边栏 会显示在Examples菜单中
{
text: 'Examples', // 分类名
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' }, // text 为显示的目录文件名 link为绑定的md文件
{ text: 'Runtime API Examples', link: '/api-examples' },
]
},
{
text: 'Test',
items: [
{ text: 'Test', link: '/test' }
]
}
],
socialLinks: [
{ icon: 'github', link: '<https://github.com/vuejs/vitepress>' }
]
}
})
如果只是搭建自己的md阅读网站，那么这样子就可以了。接下来只需要编写自己的文档并往下填充即可。但是对于有定制化需求的可以往下面进行查看。
代码实战
1. 目录用途
- .vitepress 配置文件夹
|- config.mts 配置文件
- index.md
- api-examples.md
- markdown-examples.md md文件
- package.json 无需多言
2. 设置document文件夹
为了方便分类，将所有md文件放置到document文件夹中并进行配置；
// config.mts
export default defineConfig({
srcDir: 'docs',
});
3. 自定义主题
自定义主题，即为自己定义自己网站风格，VitePress支持开发者使用vue编写自己的布局和样式，而md文件则使用布局中的Content组件进行渲染；
而在我们刚启动时会发现VitePress有一套好看的样式，所以在我们自定义中有两种方式进行自定义：
- 完全自定义：除了使用Content渲染md文件，其他布局样式自己定义
- 局部自定义：使用官方的Layout组件，提供插槽进行局部的优化
1. 设置theme文件夹
通过官方的默认配置，我们需要在.vitepress文件夹中创建theme文件夹，底下需要有一个index.ts文件；下面是一个标准案例
// index.ts
import Layout from './Layout.vue';
export default {
Layout,
enhanceApp({ app, router, siteData }) {
// ...
}
// Layout.vue
<script setup>
import { useData } from 'vitepress'
// page为当前页面数据 frontmatter为当前显示的markdown的配置
const { page, frontmatter } = useData()
</script>
<template>
<h1>Custom Layout!</h1>
<!-- 判断是不是404 -->
<div v-if="page.isNotFound">
Custom 404 page!
</div>
<!-- 判断当前是否为home文件 在md文件中进行配置 -->
<div v-if="frontmatter.layout === 'home'">
Custom home page!
</div>
<!-- 必备，用于显示markdown -->
<Content v-else />
</template>
重新启动项目 会发现我们的自定义布局已经应用上去.
2. 使用官方的layout
<!-- Layout.vue -->
<script setup>
import DefaultTheme from 'vitepress/theme';
const { Layout } = DefaultTheme;
</script>
<template>
<Layout>
<template #nav-bar-content-after>
<span>Custom</span>
</template>
</Layout>
</template>
在这里使用了官方的layout组件进行自定义布局，使用插槽进行局部替换
通过上方链接可以看到官方配置
3. 自定义页面
首先，我们得明确一个概念，即在VitePress中，md文件即为页面。而我们需要自定义页面的话，VitePress提供了在md文件中引入组件的方式，所以我们可以这么做；
编写vue组件
// .vitepress/theme/Test.vue
<template>
<div>Hello World！！！ TEST</div>
</template>
在theme/index.ts中进行全局注册
// index.ts
import Layout from './Layout.vue';
import Test from './Test.vue';
export default {
Layout,
enhanceApp({ app, router, siteData }) {
app.component("Test", Test); // 注册全局组件
// ...
},
};
在md文件中进行引入
// test.md
---
layout: test
---
<Test />
vitepress会自动引入md文件的路由，所以直接访问/test即可。
参考链接
用 VitePress 搭建电子书，绝了！VitePress写技术文档、做官网很棒，由于它极高的扩展性，做电子书更是一个 - 掘金
