VitePress建站

vitepress文档：https://vitepress.dev/zh/

环境要求

Node.js18及以上版本
此文档使用的Node.js版本是18.19.1

快速开始

在你想要创建项目的文件夹内，cmd窗口执行：npm add -D vitepress 接下来初始化VitePress，执行：npx vitepress init，会询问你几个问题：

文件结构

.
├── .vitepress                   VitePress核心目录
│  ├── theme                      主题目录
│     ├── index.js                 主题入口文件
│     ├── style.css                自定义css样式
│  ├── config.mjs                 配置文件
├── node_modules                 依赖
├── api-examples.md              官方的示例markdown
├── index.md                     主页文件
├── markdown-examples.md         官方的示例markdown
├── package.json
└── package-lock.json

启动项目

在根目录执行：npm run docs:dev

主页配置

顶部导航

顶部导航分为左侧标题，右侧导航，右侧社交按钮，都在 .vitepress/config.mjs 中配置

title：左上角的标题，也是网页的标题 description：网页head头中的 <meta name="description" content="这里是描述内容">themeConfig.nav：右上角的导航菜单，text是显示的文字，link是点击后跳转的链接。默认的配置是两个单独的按钮，若想配置下拉按钮，可以嵌套配置：

themeConfig: {
    nav: [
        {text: '主页', link: '/'}, 
        {
            text: '下拉菜单', 
            item: [
                {text: '下拉菜单1', link: '/markdown-examples'},
                {text: '下拉菜单2', link: '/api-examples'},
            ]
        }
    ]
}

themeConfig.socialLinks：右上角的社交按钮，icon是图标，可以直接粘贴svg代码，link是点击后跳转的链接

主页中部内容

底部版权信息

底部的配置，在 .vitepress/config.mjs 中配置，在themeConfig下添加footer配置：

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
    title: "标题",
    description: "head头描述",
    themeConfig: {
        //底部配置
        footer: {
	    copyright: 'Copyright © 2020-2024 版权所有 - 小太阳',
	},
    }
})

点击放大图片

借助第三方库实现，这里使用的是字节的Arco Design，用到的是image组件 文档地址：https://arco.design/vue/component/image

实现效果

处理方式说明：很简单，就是利用VitePress提供的在.md文件中使用vue组件的方式实现的。这里使用的是Arco Design的image组件，如果你使用Element Plus的image组件也是一样的。比如：

## 这是一个.md文件的标题
你问我西厂算什么东西？我现在告诉你，你们东厂不敢管的事，我们西厂管。你们东厂不敢杀的人，我们西厂杀。一句话，东厂能管的我们管，东厂不能管的我们更要管。先斩后奏，皇权特许！这就是西厂，够不够清楚，请看下方图片示例：
<a-image width="200" src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp"
  />

在VitePress中使用vue组件非常简单，这里不再赘述，如果需要请查看文档：Vitepress注册全局组件 这个.md文件VitePress最终会帮你转换成html代码，在浏览器预览图片就可以点击放大了，但有一个缺点，在.md文件中输入的vue组件代码，当使用一些所见即所得的markdown编辑工具时图片不能实时预览，比如我用的是Obsidian：

就像上图那样，vue组件只能看见代码，看不见图片预览，只有markdown的图片格式才能看见图片预览。所以还需要一点点小改动，使markdown中的图片格式保持不变，在markdown转为html时做一些处理，将图片转为使用vue组件的代码，这样即能在编辑工具中实时看到图片，又能在VitePress渲染后可以在浏览器中点击放大图片。

markdown图片格式是：![Netty架构图](../resources/笔记/Netty快速入门/Netty是什么.png)，前面中括号里是转为html后img标签的alt属性，作用是鼠标悬浮可以出现文字描述信息；后面小括号里是图片的地址，可以是本地路径也可以是网络图片的url。如果你想给图片加一个点击链接，点击图片跳转到其他页面，那可以使用[![替代文字](图片地址)](链接图片跳转地址)。

实现步骤

1. 安装 Arco Design 库

npm install --save-dev @arco-design/web-vue

2. 在.vitepress/theme/index.js引入相关文件，这里是按需引入，用哪个组件就引哪个组件要不然最后打包文件太大了，引入部分已经加了代码高亮

//注意引入css的顺序，要不然会覆盖vitepress的样式，所以在DefaultTheme前引入就可以了
import {Image} from '@arco-design/web-vue'  
import '@arco-design/web-vue/dist/arco.css'; 
import DefaultTheme from 'vitepress/theme'  
import './style.css'  
  
export default {  
	extends: DefaultTheme,   
	Layout: () => {  
		return h(DefaultTheme.Layout, null, { })  
	},
	enhanceApp({ app, router, siteData }) {
		// 将image组件注册为全局组件
		app.component("AImage", Image);  
	},  
}

3. 自定义markdown-it对图片的处理 VitePress使用markdown-it作为markdown渲染器，我们可以自定义markdown-it插件来做自定义处理。在.vitepress目录中新建markdown-it-extend目录，用于存放markdown-it自定义扩展，然后在.vitepress/markdown-it-extend目录下新建markdownItImage.js文件来处理图片。

export default function customMarkdownItPlugin(md) {  
	let defaultRender = md.renderer.rules.image  
	md.renderer.rules.image = function (tokens, idx, options, env, self) {  
		//获取token  
		let token = tokens[idx]  
		//如果是图片  
		if (token.type === 'image') {  
			let src = tokens[idx].attrGet('src');
			//返回自定义代码
			return `<a-image src="${src}" title="${token.content}" alt="${token.content}" />`  
		}
		//使用默认的处理
		return defaultRender(tokens, idx, options, env, self);  
	}  
}

这里有必要介绍的是tokens参数，因为markdown的内容都在这里面。学过编译原理都知道在做词法分析的时候会将数据转为一个一个的词法单元，也叫token，没学过也没什么所谓，因为这里获取到的tokens是已经解析好的，就当它是一个一个的记号就行了，可以自行console打印一下看看。 4. 将markdown对图片的自定义处理引入VitePress，在.vitepress/config.mjs中引入，引入部分已经加了代码高亮

import { defineConfig } from 'vitepress'  
import customMarkdownItPlugin from "./markdown-it-extend/markdownItImage.js";

export default defineConfig({
	title: '网站的标题',
	themeConfig: {
		//...省略配置
	},
	//注意，不要写在themeConfig里，它和themeConfig是同级
	markdown: {  
		config: (md) => {  
			// 使用更多的 Markdown-it 插件！  
			md.use(customMarkdownItPlugin)  
		}  
	}
})

5. 如果你想让鼠标悬浮在图片上出现一个手型的图标，需要添加全局样式

.VPDoc img {  
	cursor: pointer;  
}

到这里就已经实现完毕了，可以正常编写markdown了，也不需要在markdown里写vue组件代码了，这样即保留了markdown内容的格式，又能实现点击图片放大。默认的图片是居左的，如果你想让图片居中或居右，相信聪明的你此时已经知道该如何处理了。

图片存放目录

图片的存放目录还是依照官方文档来存放，放在public目录中，否则打包的时候不会把图片一起打包。比如：根目录是blog，文档写在blog/docs目录中，文档中引用的资源在blog/public/resource目录中，将资源放在public目录中就可以啦，如下图，引用的时候不需要再写/public了：