vitepress创建文档博客

01、网址

VitePress：vitepress.dev/

VitePress中文网：vitejs.cn/vitepress/

02、创建一个目录并进入

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

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

• 创建文件夹

   mkdir vitepress-docs && cd vitepress-docs
  

03、初始化

• 输入下面命令一直回车即可

   npm init
  

04、安装 vitepress

• 输入下面命令进行安装

   npm add -d vitepress
  

05、替换 package.json 中的 scripts

• 复制下面代码中的 scripts 替换即可

   {
     "name": "vitepress-docs",
     "version": "1.0.0",
     "main": "index.js",
     "license": "MIT",
     "devDependencies": {
       "vitepress": "^1.0.0-beta.1"
     },
     "scripts": {
       "docs:dev": "vitepress dev docs",
       "docs:build": "vitepress build docs",
       "docs:serve": "vitepress serve docs"
     }
   }
  

06、启动服务

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

   npm run docs:dev
  

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

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

07、创建文档首页

• 在 docs 文件夹下创建 index.md 文件，复制下面内容到该文件中

   ---
   {
     "layout": "home",
     "title": "首页",
     "editLink": true,
     "hero":{
       "name":"令人敬畏的项目",
       "text":"一个VitePress网站",
       "tagline":"标语",
       "image":{
         "src":"/logo.png",
         "alt":"logo"
       },
       "actions":[
         {
           "theme":"brand",
           "text":"掘金个人主页",
           "link":"/",
         },
         {
           "theme":"alt",
           "text":"码云个人主页",
           "link":"/",
         },
       ]
     },
     "features":[
       {
         "icon":"🛠️",
         "title":"标题",
         "details":"描述文本",
         "linkText":"查看详情",
         "link":"/",
       },
       {
         "icon":{
           "src":"/logo.png"
         },
         "title":"标题",
         "details":"描述文本",
         "linkText":"查看详情",
         "link":"/",
       },
       {
         "icon":{
           "dark":"/logo.png",
           "light":"/logo.png",
         },
         "title":"标题",
         "details":"描述文本",
         "linkText":"查看详情",
         "link":"/",
       },
     ]
   }
   ---
   ​
   <style>
       :root {
       --vp-home-hero-name-color: transparent;
       --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
       }
   </style>
  

08、创建配置文件 config.js

• 在 docs 文件夹下的 .vitepress 文件夹中创建 config.js 文件，复制下面内容到该文件中

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

09、创建静态文件目录 public 方便存放图片

• 在 docs 文件夹下创建 public 文件目录，目录结构如下

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

10、 config.js 配置

导航栏

 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创建文档' }
        ],
      },
    ],
  },
 }
 })

显示h2到h6标题

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

大纲标题

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

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: {
  // 页脚
     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'
     },
 }
 })

语言

 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: '../publict',
 })

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',
       })
     ]
   },
 })

:::