新建一个项目文件夹：D:\\WENJIAN\\docs-vitepress
首先在项目文件夹中，打开cmd
npm install -D vitepress
pnpm vitepress init
npx vitepress init
yarn vitepress init
vitepress v1.0.0-rc.39
T Welcome to VitePress!
|
o Where should VitePress initialize the config?
| ./
|
o Site title:
| My Awesome Project
|
o Site description:
| A VitePress Site
|
o Theme:
| Default Theme
|
o Use TypeScript for config and theme files?
| Yes
|
o Add VitePress npm scripts to package.json?
| Yes
|
— Done! Now run npm run docs:dev and start writing.
在运行pnpm vitepress init 之后，开始相关配置：
在VsCode中打开项目文件夹，新建终端，运行pnpm run docs:dev
打开Local: [<http://localhost:5173/>](<http://localhost:5173/>) 看到下图为成功案vitepress
对于主页有9项可以自定义的地方，页脚可以自己添加：
在项目文件夹.vitepress\\config.mjs 中配置，修改结点title
想要设置其不显示可以添加
export default defineConfig({
themeConfig: {
//左上角logo
logo: '/logo.png',
siteTitle: false, //标题隐藏
},
})
在index.md中定义。修改name 完成更新
为name添加渐变色：
<style>
:root {
/* 标题渐变色 */
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
}
</style>
在index.md中定义。修改text完成更新
在index.md中定义。修改tagline完成更新
在index.md中定义。修改actions完成更新
link可以跳转到外部链接，text表述为按钮的提示文字
<style>
:root {
/* brand按钮 */
--vp-button-brand-border: #F6CEEC;
--vp-button-brand-text: #F6CEEC;
--vp-button-brand-bg: #D939CD;
--vp-button-brand-hover-border: #F6CEEC;
--vp-button-brand-hover-text: #fff;
--vp-button-brand-hover-bg: #D939CD;
--vp-button-brand-active-border: #F6CEEC;
}
</style>
在index.md中定义。修改features完成更新
特性可以使用emoji表情、图片以及SVG创建图形
---
features:
- icon: 📝
title: 专注于您的内容
details: 只需使用 Markdown 即可轻松创建精美的文档网站
- icon:
dark: /logo.png
light: /logo-light.png
title: 享受Vite DX
details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins.
- icon: <svg xmlns="<http://www.w3.org/2000/svg>" width="32" height="32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6 3.22-5.6Z"/><path fill="#41b883" d="m2 3.925 14 24.15 14-24.15h-5.6L16 18.415 7.53 3.925Z"/><path fill="#35495e" d="M7.53 3.925 16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"/></svg>
title: 使用 Vue 进行定制
details: 直接在 Markdown 中使用 Vue 语法和组件，或使用 Vue 构建自定义主题
- icon: 🚀
title: 快速发布网站
details: 使用静态 HTML 进行快速初始加载，使用客户端路由进行快速加载后导航
---
可以做成跳转链接
---
features:
- icon: 📝
title: 专注于您的内容
details: 只需使用 Markdown 即可轻松创建精美的文档网站
- icon:
dark: /logo.png
light: /logo-light.png
title: 享受Vite DX
details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins.
link: <https://vitejs.cn/>
linkText: Vite
---
在项目文件夹.vitepress\\config.mjs 中配置，修改结点themeConfig nav
可以添加有下拉菜单的形式的nav，就需要加一个 iteams
nav: [
{ text: 'Home', link: '/' },
{ text: 'More', link: '/markdown-examples' },
// 添加下拉菜单
{
text: 'Examples',
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' },
{ text: 'Runtime API Examples', link: '/api-examples' }
]
}
],
给下拉菜单赋予分组标题，就要再次嵌套 iteams
export default defineConfig({
themeConfig: {
//导航栏
nav: [
{ text: '首页', link: '/' },
{
text: '指南',
items: [
{
// 分组标题1
text: '介绍',
items: [
{ text: '前言', link: '/preface' },
],
},
{
// 分组标题2
text: '基础设置',
items: [
{ text: '快速上手', link: '/getting-started' },
{ text: '配置', link: '/configuration' },
{ text: '页面', link: '/page' },
{ text: 'Frontmatter', link: '/frontmatter' },
],
},
{
// 分组标题3
text: '进阶玩法',
items: [
{ text: 'Markdown', link: '/Markdown' },
{ text: '静态部署', link: '/assets' },
],
},
],
},
{ text: 'VitePress', link: '<https://vitepress.dev/>' },
],
},
})
在项目文件夹.vitepress\\config.mjs 中配置，修改结点themeConfig socialLinks
页脚的添加方式：
在项目文件夹.vitepress\\config.mjs 中修改添加：footer结点：位置为defineConfig themeConfig footer
import { defineConfig } from 'vitepress'
// <https://vitepress.dev/reference/site-config>
export default defineConfig({
title: "My Awesome Project",
// 用来做SEO
description: "A VitePress Site",
themeConfig: {
// <https://vitepress.dev/reference/default-theme-config>
nav: [
{ text: 'Home', link: '/' },
{ text: 'Examples', link: '/markdown-examples' }
],
sidebar: [
{
text: 'Examples',
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' },
{ text: 'Runtime API Examples', link: '/api-examples' }
]
}
],
socialLinks: [
{ icon: 'github', link: '<https://github.com/vuejs/vitepress>' }
],
// footer
footer:
{ copyright: "Copyright@ 2024 Dolimence Wei" }
}
})
需要将所有的图片资源素材放在根目录下public文件夹下
在index.md中可以添加背景图
image:
src: /index-image2.svg
alt: DoliL in ViteSite
<style>
:root {
/*图标背景渐变色 */
--vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
--vp-home-hero-image-filter: blur(40px);
}
</style>
logo的添加在config.mjs中添加，添加位置为defineConfig themeConfig
import { defineConfig } from 'vitepress'
// <https://vitepress.dev/reference/site-config>
export default defineConfig({
title: "DoliL in VitePress",
// 用来做SEO
description: "A VitePress Site",
themeConfig: {
// logo添加在这里
logo: '/public/logo.svg',
// <https://vitepress.dev/reference/default-theme-config>
nav: [
{ text: 'Home', link: '/' },
{ text: 'More', link: '/markdown-examples' },
],
socialLinks: [
{ icon: 'github', link: '<https://github.com/vuejs/vitepress>' }
],
// footer
footer:
{ copyright: "Copyright@ 2024 Dolimence Wei" }
}
})
默认是三边栏布局，左边是sidebar配置，右边是显示的文章目录（默认显示一二级）
sidebar配置，config.mjs
sidebar: [
{
text: 'Examples',
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' },
{ text: 'Runtime API Examples', link: '/api-examples' }
]
},
{
text: 'Examples',
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' },
{ text: 'Runtime API Examples', link: '/api-examples' }
]
}
],
侧边栏可以折叠，添加 collapsed选项，它会显示一个切换按钮来隐藏/显示
export default defineConfig({
themeConfig: {
//侧边栏
sidebar: [
{
text: 'Section Title A',
collapsed: false,
items: [...]
},
],
},
})
侧边栏(移动端), 更改手机端菜单文字显示，默认 Menu
export default defineConfig({
themeConfig: {
//侧边栏文字更改(移动端)
sidebarMenuLabel:'目录',
},
})
多侧边栏
可能会根据页面路径显示不同的侧边栏。例如，如本站点所示，可能希望在文档中创建单独的侧边栏，例如“指南”页面和“配置参考”页面。
为此，首先将你的页面组织到每个所需部分的目录中：
.
├─ guide/
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ config/
├─ index.md
├─ three.md
└─ four.md
然后，更新配置以定义每个部分的侧边栏。这一次，应该传递一个对象而不是数组。
export default {
themeConfig: {
sidebar: {
// 当用户位于 `guide` 目录时，会显示此侧边栏
'/guide/': [
{
text: 'Guide',
items: [
{ text: 'Index', link: '/guide/' },
{ text: 'One', link: '/guide/one' },
{ text: 'Two', link: '/guide/two' }
]
}
],
// 当用户位于 `config` 目录时，会显示此侧边栏
'/config/': [
{
text: 'Config',
items: [
{ text: 'Index', link: '/config/' },
{ text: 'Three', link: '/config/three' },
{ text: 'Four', link: '/config/four' }
]
}
]
}
}
}
文档内容，在相应的.md 文件中编辑：根目录中的api-examples.md
根据文章内容自动生成。右侧导航栏默认索引的是md文件的一二级标题，可能需要定义索引的标题级别和On this page这个说明。这个时候需要在config.mjs中配置下面这两个选项，outlineTitle用于替代On this page。outline定义展示的标题级别，这里定义2-6级。outline定义参数可以为”deep”，同样为2-6
使用脚本可以实现自动生成侧边栏，根据一个目录下面的所有md文件自动生成路由。在根目录下创建\\.vitepress\\utils\\auto_sidebar.mjs
import path from "node:path";
import fs from "node:fs";
// 文件根目录
const DIR_PATH = path.resolve();
// 白名单,过滤不是文章的文件和文件夹
const WHITE_LIST = [
"index.md",
".vitepress",
"node_modules",
".idea",
"assets",
];
// 判断是否是文件夹
const isDirectory = (path) => fs.lstatSync(path).isDirectory();
// 取差值
const intersections = (arr1, arr2) =>
Array.from(new Set(arr1.filter((item) => !new Set(arr2).has(item))));
// 把方法导出直接使用
function getList(params, path1, pathname) {
// 存放结果
const res = [];
// 开始遍历params
for (let file in params) {
// 拼接目录
const dir = path.join(path1, params[file]);
// 判断是否是文件夹
const isDir = isDirectory(dir);
if (isDir) {
// 如果是文件夹,读取之后作为下一次递归参数
const files = fs.readdirSync(dir);
res.push({
text: params[file],
collapsible: true,
items: getList(files, dir, `${pathname}/${params[file]}`),
});
} else {
// 获取名字
const name = path.basename(params[file]);
// 排除非 md 文件
const suffix = path.extname(params[file]);
if (suffix !== ".md") {
continue;
}
res.push({
text: name,
link: `${pathname}/${name}`,
});
}
}
// 对name做一下处理，把后缀删除
res.map((item) => {
item.text = item.text.replace(/\\.md$/, "");
});
return res;
}
export const set_sidebar = (pathname) => {
// 获取pathname的路径
const dirPath = path.join(DIR_PATH, pathname);
// 读取pathname下的所有文件或者文件夹
const files = fs.readdirSync(dirPath);
// 过滤掉
const items = intersections(files, WHITE_LIST);
// getList 函数后面会讲到
return getList(items, dirPath, pathname);
};
使用时，导入函数
import { set_sidebar } from "./utils/auto_sidebar.mjs"; // 改成自己的路径
直接使用。第一个/front-end/react常常是nav的link，这个set_sidebar传递的参数是相对于根路径的文件夹路径，返回的是每个文件夹中文件的名称和链接。在传入的文件夹名称参数后，会返回除了该文件夹下index.md之外的所有文件列表。