前言

简介

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。

简而言之，可构建你自己的 技术文档站点；

环境要求

Node.js 18 及以上版本。我使用 v20.11.0

创建

第一步： 全局安装

npm i vitepress -g

第二步： 在项目目录下执行 安装向导

npx vitepress init

根据提示完成如下配置指导，注意代码 16 行，没有使用 Typescript

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  No
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

如图

此时的文档目录如下

.
├─ docs
|   ├─ .vitepress            
|   |  └─ config.mjs		 # 配置文件
|   ├─ api-examples.md       # markdown 文件 
|   ├─ markdown-examples.md	 # markdown 文件 
|   └─ index.md				 # markdown 文件 
└─ package.json	             # 插件依赖

第三步： 在 package.json 中加上依赖插件 vitepress。如下代码第 2-4 行。

注意 版本号是 1.0.0-rc.40，现在最新版 1.0.0-rc.44报错 No matching version found for perfect-debounce@^1.0.0.

{"devDependencies": {"vitepress": "1.0.0-rc.40"},"scripts": {"docs:dev": "vitepress dev docs","docs:build": "vitepress build docs","docs:preview": "vitepress preview docs"}
}

第四步： 安装依赖

npm i

第五步： 启动系统

npm run docs:dev

启动效果如下，默认地址 http://localhost:5173：

配置

配置文件 docs/.vitepress/config.mjc

站点配置

站点配置是全局设置。本文仅列出我常用的，想了解更多请参考 官网之站点配置。

title

export default defineConfig({title: "我的前端技术站点",
})

description

export default defineConfig({description: "我的前端技术站点",
})

lang

export default defineConfig({lang: 'zh-Hans',
})

base

// 建议定义为常量，后续功能需要
const base = '/myroute/';export default defineConfig({base,
})

head

// 建议定义为常量，后续功能需要
const base = '/mypath/';export default defineConfig({base,head: [['link', { rel: 'icon', href: `${base}logo.png` }],['link', { rel: 'stylesheet', href: `${base}css/index.css` }],],
})

主题配置

此篇仅介绍 默认主题 的配置，想了解更多请参考 官网之默认主题。

导航栏

显示在页面顶部的导航栏，注意都在属性 themeConfig 下。包含：

• logo 站点图标；
• siteTile 站点标题；
• nav 导航链接；
• socialLinks 社交链接；

PS：我以前狭隘了，使用 vuepress 时，一直理解仅 nav 属性是导航栏…

export default defineConfig({themeConfig: {siteTitle: 'My Custom Title',   // 站点标题logo: '/logo.png',			    // 站点图标nav: [							// 导航链接{ text: 'Home', link: '/' },{ text: 'Examples', link: '/markdown-examples' }],socialLinks: [					// 社交链接{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }]}
})

侧边栏

侧边栏是文档的主要导航块。可以在 themeConfig.sidebar 中配置侧边栏菜单。

• .md文件从目录 ./docs/ 下开始；
• 便于统一管理.md文件，可放在同一目录，例如新建目录 ./docs/guide/；
• 但首页文件 index.md 还是放在 ./docs/ 下；
• 属性 sidebar ，基本用法是 数组类型，多侧边栏是对象类型；

export default defineConfig({themeConfig: {sidebar: [{text: 'Examples',items: [{ text: 'Markdown Examples', link: '/guide/markdown-examples' },{ text: 'Runtime API Examples', link: '/guide/api-examples' }]}],}
})

其它

outline.label

export default defineConfig({themeConfig: {outline: {label: '页面导航'},}
})