vitepress文档博客

简客陈
466 阅读6分钟

VitePress

网址

VitePress：vitepress.dev/

VitePress中文网：vitejs.cn/vitepress/

在 Vite 项目中使用VitePress

如果你想在vite搭建的项目中使用VitePress，先新建好项目直接安装使用VitePress就好

创建项目

  • 我的node版本16.19.0
  • vitepress-project为项目名称可修改名称
  • 回车选择vue+js
  npm create vite@latest vitepress-project

进入项目安装依赖运行项目

  cd vitepress-project
  npm install

启动服务

  npm run dev

创建一个目录并进入

创建一个项目文件夹，下面vitepress-docs为项目文件夹

注意：项目文件夹不能为中文

 mkdir vitepress-docs && cd vitepress-docs

初始化项目

 npm init -y

安装 vitepress

 npm add -d vitepress

在 package.json 中配置 scripts 脚本命令

可以根据自己的习惯配置

 "scripts": {
   "docs:dev": "vitepress dev docs",
   "docs:build": "vitepress build docs",
   "docs:serve": "vitepress serve docs"
 }

或

 "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "serve": "vitepress serve"
  }

VitePress 启动服务

输入下面命令运行启动项目预览，启动项目后会生成一系列基本文件夹

具体启动命令根据自己配置的来即可

npm run docs:dev

或

npm run dev

如果没有生成基本文件夹就手动创建目录结构如下

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

VitePress 打包

npm run docs:build

或

npm run build

创建文档首页

在 .vitepress 同级创建 index.md 文件，随便输点内容即可看到效果

站点配置/config.ts

在.vitepress下创建配置文件config.js

.vitepress/config.ts

export default {
  
}

或者

import { defineConfig } from 'vitepress'
export default defineConfig({
  
})

导航栏

import { defineConfig } from 'vitepress'
export default defineConfig({
// 主题配置
themeConfig: {
   // 导航
   nav: [
     {
       text: '首页',
       link: '/index.md',
     },
     {
       text: '文章',
       link: '/article/vitepress创建文档',
     },
     {
       text: '页面导航',
       activeMatch: '/base/',
       items: [
         {
           text: '页面模板',
           items: [
             { text: '首页', link: '/base/home.md' },
             { text: '文档', link: '/base/doc.md' },
             { text: '团队', link: '/base/team.md' },
           ]
         },
         {
           text: '其他页面',
           items: [
             { text: '其他页面', link: '/' },
             { text: '其他页面', link: '/index' },
           ]
         },
       ]
     }
   ],
  }
})

侧栏

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 侧栏
   sidebar: {
     '/article/': [
       {
         text: '文章',
         items: [
           { text: 'vitepress创建文档', link: '/article/vitepress创建文档' },
           { text: 'css笔记', link: '/article/vitepress创建文档' },
           { text: 'css笔记', link: '/article/vitepress创建文档' }
         ],
       },
     ],
   },
  }
})

切换主题

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 切换主题
  appearance: true, // 默认 true，设为 false 则无法切换dark/light主题，可选 'dark' true false
})

显示h2到h6标题

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 显示h2到h6标题
   outline: 'deep',//[2,6]
  }
})

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   outline: {
			level: "deep", // 右侧大纲标题层级
		},
  }
})

大纲标题

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 大纲标题
   outlineTitle: '文章目录',
  }
})

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   outline: {
			label: "目录", // 右侧大纲标题文本配置
		},
  }
})

logo

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // logo
   logo: '/logo.png',
  }
})

网站标题

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 网站标题
      siteTitle: '网站标题',
  }
})

小侧栏位置

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   //	小侧栏位置,'left'、false、true
      aside: 'left',
  }
})

社交链接

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 社交链接
   socialLinks: [
     { icon: 'discord', link: '' },
     { icon: 'facebook', link: '' },
     { icon: 'github', link: '' },
     { icon: 'instagram', link: '' },
     { icon: 'linkedin', link: '' },
     { icon: 'mastodon', link: '' },
     { icon: 'slack', link: '' },
     { icon: 'twitter', link: '' },
     { icon: 'youtube', link: '' },
     {
       icon: {
          svg: ''
       },
       link: ''
     },
   ],
  }
})

编辑此页面

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 编辑此页面
   editLink: {
     pattern: 'https://e.gitee.com/ckjdocs/repos/ckjdocs/vitepress-template/tree/master/docs/:path',
     text: '在gitee上编辑此页面'
   },
  }
})

上次更新时间

import { defineConfig } from 'vitepress'
export default defineConfig({
	// 上次更新时间
	lastUpdated: true,
})

上次更新时间之前显示的前缀文本

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 上次更新时间之前显示的前缀文本
   lastUpdatedText: 'Updated Date',
  }
})

返回顶部

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
		// 返回顶部
    returnToTopLabel: '返回顶部',
  }
})

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   // 返回顶部
		backToTop: {
			text: "返回顶部",
		},
  }
})

页脚

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
		// 页脚
    footer: {
      message: '邮箱：xxxxxxxxx@qq.com',
      copyright: '免责声明：本站为个人博客，本站不贩卖软件，所有内容不作为商业行为。本网站所提供的所有资源均来源于网络，仅供学习和交流使用，版权归原作者所有。本网站不承担任何法律责任，亦不承担任何赔偿责任。如果您认为本网站某些资源侵犯了您的版权，请及时联系我们，并提供相关证明文件，我们将立即删除相关内容。'
    },
  }
})

文档页脚

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
   //文档页脚
    docFooter: {
      prev: '上一篇',
      next: '下一篇'
    },
  }
})

搜索

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 主题配置
  themeConfig: {
     // 搜索
    search: {
      provider: 'local',
			options: {
				translations: {
					button: {
						buttonText: '搜索文档',
						buttonAriaLabel: '搜索文档'
					},
					modal: {
						noResultsText: '无法找到相关结果',
						resetButtonTitle: '清除查询条件',
						footer: {
							selectText: '选择',
							navigateText: '切换'
						}
					}
				}
			}
    },
  }
})

语言

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 语言
  lang: 'zh-cn',
})

标题

import { defineConfig } from 'vitepress'
export default defineConfig({
	// 标题
	title: "标题",
})

标题模板

import { defineConfig } from 'vitepress'
export default defineConfig({
	// 标题模板
	titleTemplate: '标题模板',
})

网站说明

import { defineConfig } from 'vitepress'
export default defineConfig({
	// 网站说明
	description: "网站说明",
})

部署站点的基本 URL

import { defineConfig } from 'vitepress'
export default defineConfig({
	// 部署站点的基本 URL
	base: '/docs/',
})

代码块中启用行号

import { defineConfig } from 'vitepress'
export default defineConfig({
  // markdown配置
  markdown: {
   // 是否在代码块中启用行号
   lineNumbers: true,
  },
})

忽略死链接

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 忽略死链接
  ignoreDeadLinks: true,
})

存储markdown的项目根目录

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 存储markdown的项目根目录
  srcDir: './src',
})

项目打包输出位置

import { defineConfig } from 'vitepress'
export default defineConfig({
  // 项目打包输出位置
  outDir: '../dist',
})

ico图标配置

import { defineConfig } from 'vitepress'
export default defineConfig({
  // ico图标配置
  head: [
   ['link', { rel: 'icon', href: '/logo.png' }],
  ],
})

搜索插件

// npm install vitepress-plugin-search --save-dev
import { SearchPlugin } from "vitepress-plugin-search";
import { defineConfig } from 'vitepress'
export default defineConfig({
	vite: {
		plugins: [
     // 搜索插件
     SearchPlugin({
       previewLength: 62,
       buttonLabel: "搜索",
       placeholder: "搜索文档",
       tokenize: 'full',
     })
		]
	},
})

图片查看插件fancybox

将fancybox插件资源放到public资源目录下，在站点配置中head配置

安装Markdown 解析器插件markdown-it-custom-attrs

npm install markdown-it-custom-attrs --save

export default {
    head:[
        ["link",{ rel: "stylesheet", href: "https://cdn.jsdelivr.net/npm/@fancyapps/ui/dist/fancybox.css" },],
        ["script", { src: "https://cdn.jsdelivr.net/npm/@fancyapps/ui@4.0/dist/fancybox.umd.js" }],
    ]
}

import { defineConfig } from 'vitepress'
import mdItCustomAttrs from 'markdown-it-custom-attrs'
export default defineConfig({
	head: [
		["link", { rel: "stylesheet", href: "/fancybox/fancybox.css" },],
		["script", { src: "/fancybox/fancybox.umd.js" }],
	],
  markdown: {
		config: (md) => {
      //图片放大预览配置
			md.use(mdItCustomAttrs, 'image', {
				'data-fancybox': "gallery"
			})
		}
	},
})

侧边栏和导航栏插件vitepress-plugin-autobar

npm install vitepress-plugin-autobar --save-dev

静态资源管理

在 .vitepress 同级创建静态文件目录public方便存放资源

自定义主题

.vitepress/theme/index.ts

import DefaultTheme from "vitepress/theme";
export default {
  ...DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    
  }
}

使用组件

import DefaultTheme from "vitepress/theme";
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/reset.css';
export default {
  ...DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    // 使用组件
    app.use(Antd);
  }
}

注册全局组件

import DefaultTheme from "vitepress/theme";
import home from "../components/home.vue";
export default {
  ...DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    // 注册全局组件
    app.component("Home", home);
  }
}

安装 Ant Design Vue

npm install ant-design-vue@4.x --save

安装 vue

npm i -D vue

安装 ts

 npm i typescript --save-dev
avatar
文章
阅读
粉丝