ToB企服应用市场:ToB评测及商务社交产业平台

标题: 使用 Vitepress 构建博客并摆设到 github 平台 [打印本页]

---

作者: 王國慶    时间: 2024-8-11 13:49
标题: 使用 Vitepress 构建博客并摆设到 github 平台
媒介

近来写了好多篇 Chrome 浏览器插件相干的文章，有十几二十篇，就想着构建个博客，用来放置相应的文章。
正好前段时间看到 VitePress 1.0.0 发布了，而且是用 markdown 写文章，正好写插件文章的时候文章都是 md 格式，全部用下这个然后顺便写一篇使用教程。
Chrome 插件开发博客地点：https://18055975947.github.io/extension/
一、VitePress

VitePress 官网：VitePress 中文版
1. 什么是 VitePress

   VitePress 是一个静态站点天生器 (SSG)，专为构建快速、以内容为中心的站点而筹划。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并天生可以轻松摆设到任何地方的静态 HTML 页面。
  2. 性能

• 快速的初始加载
  
• 加载完成后可以快速切换
  
• 高效的交互
  

二、项目构建

1. 新建项目

   NodeJS 版本须要 18 及以上版本

1. mkdir vitepress-demo

复制代码

2. 配置项目

2.1. 项目初始化

1. pnpm init

复制代码

2.2. 安装 VitePress

1. pnpm add -D vitepress

复制代码

2.3. 初始化 VitePress

1. pnpm vitepress init

复制代码

初始化之后，会有对应的项目题目须要举行填写，示比方下：

3. 项目目录

1. tree -a -I 'node_modules'

复制代码

1. .
2. ├── docs
3. │   ├── .vitepress
4. │   │   └── config.mts
5. │   ├── api-examples.md
6. │   ├── index.md
7. │   └── markdown-examples.md
8. ├── package.json
9. └── pnpm-lock.yaml

复制代码

在 docs 文件夹中创建 public 文件夹，用于存放项目图片

1. .
2. ├── docs
3. │   ├── .vitepress
4. │   │   └── config.mts
5. │   ├── api-examples.md
6. │   ├── index.md
7. │   ├── markdown-examples.md
8. │   └── public # 增加 public 文件夹，存放项目开发使用的图片
9. ├── package.json
10. └── pnpm-lock.yaml

复制代码

4. 项目文件结构

• docs 文件夹：VitePress 项目标根目录
  
  
  
  • .vitepress：项目标配置文件、开发缓存、构建 dist 输出等
    
    
    
    • config.mts：项目配置文件
      
    
    
  • index.md：首页入口文件
    
  • **.md：其他页面
    
  • public：资源存放文件夹
    
  
  

5. 运行项目

1. pnpm run docs:dev

复制代码

浏览器打开：http://localhost:5174/

可以看出我们设置的 site title 和 site description 字段已经展示在页面中了
三、项目开发

1. 首页

一般是指 index.md 文件
1.1. Layout

指定页面的布局
   VitePress 默认主题提供了一个首页布局，可以通过 frontmatter 指定 layout: home 在任何页面上使用它
  1.1.1. 类型

doc | home | page
1.1.2. 数据值

• doc：将默认文档样式应用于 .md 文件内容
  
• home：主页的特殊布局
  
• page：和 doc 类似，但不对内容应用任何样式
  

1.1.3. 示例

1. ---
2. layout: home
3. ---

复制代码

1.1.4. 页面展示

home 展示

---

doc 展示

---

page 展示

1.2. Hero

hero 部分位于主页顶部。
当 layout 设置为 home 时，hero 配置才会生效。

1.2.1. 类型

1. interface Hero {
2.   // `text` 上方的字符，带有品牌颜色
3.   // 预计简短，例如产品名称
4.   name?: string
5.   // hero 部分的主要文字，
6.   // 被定义为 `h1` 标签
7.   text: string
8.   // `text` 下方的标语
9.   tagline?: string
10.   // text 和 tagline 区域旁的图片
11.   image?: ThemeableImage
12.   // 主页 hero 部分的操作按钮
13.   actions?: HeroAction[]
14. }

复制代码

• name：文档标题
  
• text：副标题/形貌
  
• tagline：文档标语
  
• image：右侧图片
  
• actions：操纵按钮
  
  
  
  • theme：brand | alt 按钮主题，只有这两种主题，默认为 brand
    
    
    
    • brand：蓝色背景按钮
      
    • alt：灰色背景按钮
      
    
    
  • text：按钮文案
    
  • link：按钮的链接
    
  
  

1.2.2. 示例

找一张 ext.svg 图标放在 public 文件夹中

1. ---
2. layout: home
4. hero:
5.   name: "My VitePress Demo Project"
6.   text: "This is my VitePress demo project"
7.   tagline: "My great project tagline"
8.   image:
9.     src: /ext.svg
10.     alt: Chrome 浏览器插件
11.   actions:
12.     - theme: brand
13.       text: Markdown Examples
14.       link: /markdown-examples
15.     - theme: alt
16.       text: API Examples
17.       link: /api-examples
18.     - theme: brand
19.       text: extension
20.       link: https://18055975947.github.io/extension/
21.       target: _blank
22.       rel: external
23. ---

复制代码

1.2.3. 页面展示

1.3. Features

可以在 Hero 部分之后列出任意数量的 Feature

1.3.1. 类型

1. interface Feature {
2.   // 在每个 feature 框中显示图标
3.   icon?: FeatureIcon
4.   // feature 的标题
5.   title: string
6.   // feature 的详情
7.   details: string
8.   // 点击 feature 组件时的链接，可以是内部链接，也可以是外部链接。
9.   link?: string
10.   // feature 组件内显示的链接文本，最好与 `link` 选项一起使用
11.   linkText?: string
12.   // `link` 选项的链接 rel 属性
13.   rel?: string
14.   // `link` 选项的链接 target 属性
15.   target?: string
16. }

复制代码

• icon：图标
  
• title：标题
  
• details：形貌
  
• link：跳转链接
  

1.3.2. 示例

找一些对应的图标放在 public 文件夹中

1. ---
2. layout: home
4. features:
5.   - title: 什么是浏览器插件？
6.     icon:
7.       src: /ext.svg
8.     details: Chrome 插件可通过自定义界面、观察浏览器事件和修改网络来提升浏览体验。
9.   - title: Chrome 插件是如何构建的？
10.     icon:
11.       src: /develop.svg
12.     details: 使用与创建 Web 应用相同的 Web 技术来构建扩展程序：HTML、CSS 和 JavaScript。
13.   - title: Chrome 插件可以做些什么？
14.     icon:
15.       src: /ext-2.svg
16.     details: 设计界面、控制浏览器、管理插件、覆盖网页和设置、控制网络、注入 JS 和 CSS、录音和屏幕截图
17.   - title: Vue 开发插件
18.     icon:
19.       src: /vue.svg
20.     details: 是一个使用 Vue.js 框架开发的 Chrome 插件，旨在为开发者展示如何使用 Vue.js 构建强大的浏览器扩展。
21.     link: https://juejin.cn/post/7330227149177028617
22.     linkText: 查看详情
23.   - title: React 开发插件
24.     icon:
25.       src: /react.svg
26.     details: 是一个使用 React.js 框架开发的 Chrome 插件，旨在为开发者展示如何使用 React.js 构建强大的浏览器扩展。
27.     link: https://juejin.cn/post/7349936384512213027
28.     linkText: 查看详情
29.   - title: 实用插件推荐
30.     icon:
31.       src: /tj.svg
32.     details: 推荐一些对前端开发来说实用的 Chrome 插件。
33.     link: https://juejin.cn/post/7327893130572824611
34.     linkText: 查看详情
35. ---

复制代码

1.3.3 页面展示

1.4. 其他

假如到这个时候你以为在首页 md 文件中还没有满意你的其他需求，可以在分隔符下继续以 md 的格式开发新内容。
1.4.1. 添加 MD 内容

1. ## 首页模块 MD 文档
3. MD 文件

复制代码

1.4.2 引入 MD 文件

1.4.2.1. 新建 MD 文件

在 docs 文件夹下创建 components 文件夹并创建 test.md 文件，并写入以下内容

1. ---
2. layout: page
3. ---
5. ## Components
7. ### test 模块
9. 这个模块是 `components` 文件夹下的 `test` 模块

复制代码

1. .
2. docs/components
3. └── test.md

复制代码

1.4.2.2. 在 index.md 文件引入

使用<!--@include: xxx.md--> 的格式引入
在 index.md 文件添加以下内容

1. 下面是添加 `style` 标签和引入 `md` 文件
3. <style module>
4. article>img{
5.   height: 48px;
6. }
7. </style>
9. <!--@include: ./components/test.md-->

复制代码

1.4.2.3. 页面展示

• 引入 MD 文件展示
  
  
  
  
• Style 标签样式展示
  

2. 导航栏

   Nav 是显示在页面顶部的导航栏。它包含站点标题、全局菜单链接等。
  

导航栏模块的配置是通过 docs/.vitepress/config.mts 文件配置的
config.mts 文件内容

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   themeConfig: {
6.     nav: [
7.       { text: 'Home', link: '/' },
8.       { text: 'Examples', link: '/markdown-examples' }
9.     ],
10.     sidebar: [
11.       {
12.         text: 'Examples',
13.         items: [
14.           { text: 'Markdown Examples', link: '/markdown-examples' },
15.           { text: 'Runtime API Examples', link: '/api-examples' }
16.         ]
17.       }
18.     ],
19.     socialLinks: [
20.       { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
21.     ]
22.   }
23. })

复制代码

2.1. 站点标题和图标：sitTitle、logo

2.1.1. 在 themeConfig 中添加 logo 和 siteTitle 字段

2.1.1.1. 类型

string：logo 和 siteTitle 都是 string 类型
2.1.1.2. themeConfig 配置示例

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   themeConfig: {
6.     logo: '/ext.svg',
7.     siteTitle: 'Project SitTitle',
8.   }
9. })

复制代码

2.1.2. 页面展示

可以看出 logo 已经加上了，而且 sitTitle 字段覆盖了 title 字段
默认情况下，以 config.title 作为站点的标题，但是假如想更改标题，可以设置 themeConfig 中的 sitTitle 字段。
2.2. 搜索模块：search

   VitePress 支持使用浏览器内索引举行含糊全文搜索。
  2.2.1. 在 themeConfig 中添加 search 字段

2.2.1.1. search 字段数据类型

object

1. { provider: 'local'; options?: LocalSearchOptions }
2. | { provider: 'algolia'; options: AlgoliaSearchOptions }

复制代码

2.2.1.2. themeConfig 配置示例

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   themeConfig: {
6.     logo: '/ext.svg',
7.     siteTitle: 'Project SitTitle',
8.     search: {
9.       provider: 'local'
10.     },
11.   }
12. })

复制代码

2.2.2. 页面展示

2.2.3. 搜索效果展示

2.3. 导航链接：nav

   可以界说 themeConfig.nav 选项以将链接添加到导航栏。
  【Chrome 浏览器插件开发实践指南】 文档的 Nav 导航

可以看到，不但可以配置单个链接，也可以配置下拉列表，我们就按照上面的配置来重新在我们现在的项目中配一遍
2.3.1 创建对应的文件夹和对应的 index.md 文件

创建 basic、api、core、summarize、teach、team 文件夹，并在此中创建 index.md 文件，如下：

1. .
2. ├── docs
3. │   ├── api
4. │   │   └── index.md
5. │   ├── basic
6. │   │   └── index.md
7. │   ├── core
8. │   │   └── index.md
9. │   ├── index.md
10. │   ├── summarize
11. │   │   └── index.md
12. │   ├── teach
13. │   │   └── index.md
14. │   └── team
15. │       └── index.md

复制代码

2.3.2. 在 themeConfig 中添加 nav 字段

2.3.2.1. nav 字段数据类型

数组：NavItem[]

1. type NavItem = NavItemWithLink | NavItemWithChildren
2. interface NavItemWithLink {
3.   text: string
4.   link: string
5.   activeMatch?: string
6.   target?: string
7.   rel?: string
8.   noIcon?: boolean
9. }
10. interface NavItemChildren {
11.   text?: string
12.   items: NavItemWithLink[]
13. }
14. interface NavItemWithChildren {
15.   text?: string
16.   items: (NavItemChildren | NavItemWithLink)[]
17.   activeMatch?: string
18. }

复制代码

2.3.2.2. themeConfig 配置示例

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   themeConfig: {
6.     logo: '/ext.svg',
7.     siteTitle: 'Project SitTitle',
8.     search: {
9.       provider: 'local'
10.     },
11.     nav: [
12.       {
13.         text: '基础',
14.         link: '/basic/index'
15.       },
16.       {
17.         text: 'API',
18.         link: '/api/index'
19.       },
20.       {
21.         text: '核心篇',
22.         link: '/core/index'
23.       },
24.       {
25.         text: '实战教学篇',
26.         items: [
27.           {
28.             text: '原生 JS 开发',
29.             link: '/teach/index'
30.           },
31.           {
32.             text: 'Vue',
33.             link: '/teach/index'
34.           },
35.           {
36.             text: 'React',
37.             link: '/teach/index'
38.           },
39.           {
40.             text: 'CRXJS Vue',
41.             link: '/teach/index'
42.           },
43.           {
44.             text: 'CRXJS React',
45.             link: '/teach/index'
46.           }
47.         ]
48.       },
49.       {
50.         text: '实用插件推荐',
51.         link: '/summarize/index'
52.       },
53.       {
54.         text: '团队',
55.         link: '/team/index'
56.       }
57.     ],
58.   }
59. })

复制代码

2.3.3. 页面效果展示

2.4. 社交账户链接：socialLinks

   可以界说此选项以在导航栏中展示带有图标的社交帐户链接。
  2.4.1. 在 themeConfig 中添加 socialLinks 字段

2.4.1.1. socialLinks 字段数据类型

数组：SocialLink[]

1. interface SocialLink {
2.   icon: SocialLinkIcon
3.   link: string
4.   ariaLabel?: string
5. }

复制代码

2.4.1.2. themeConfig 配置示例

1. export default defineConfig({
2.   themeConfig: {
3.     ...,
4.     socialLinks: [
5.           {
6.             icon: {
7.               svg: '<svg t="1713434729459" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="35275" width="64" height="64"><path d="M512 960c-246.4 0-448-201.6-448-448s201.6-448 448-448 448 201.6 448 448-201.6 448-448 448z" fill="#D81E06" p-id="35276"></path><path d="M721.664 467.968h-235.52a22.272 22.272 0 0 0-20.736 20.736v51.776c0 10.368 10.368 20.736 20.736 20.736H628.48c10.368 0 20.736 10.304 20.736 20.672v10.368c0 33.664-28.48 62.08-62.144 62.08H392.896a22.272 22.272 0 0 1-20.672-20.672V436.928c0-33.664 28.48-62.08 62.08-62.08h287.36a22.272 22.272 0 0 0 20.736-20.736v-51.84a22.272 22.272 0 0 0-20.736-20.672h-287.36A152.96 152.96 0 0 0 281.6 434.368v287.36c0 10.304 10.368 20.672 20.736 20.672h302.848c75.072 0 137.216-62.08 137.216-137.216v-116.48a22.272 22.272 0 0 0-20.736-20.736z" fill="#FFFFFF" p-id="35277"></path></svg>'
8.             },
9.             link: 'https://gitee.com/guoqiankun/my-vue3-plugin/tree/react_vite_chrome/'
10.           },
11.           {
12.             icon: {
13.               svg: '<svg t="1713408654979" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="6736" width="64" height="64"><path d="M512 1024C229.2224 1024 0 794.7776 0 512 0 229.2224 229.2224 0 512 0c282.7776 0 512 229.2224 512 512 0 282.7776-229.2224 512-512 512z m17.066667-413.525333c34.850133 4.352 68.778667 5.12 102.741333 2.0992 23.04-2.048 44.817067-8.362667 64.170667-21.9136 38.212267-26.794667 49.783467-85.1968 24.251733-123.050667-14.626133-21.7088-36.8128-30.344533-60.757333-35.498667-35.054933-7.543467-70.4512-5.751467-105.847467-3.413333-5.666133 0.3584-6.7584 3.072-7.236267 8.209067-3.072 32.682667-6.536533 65.314133-9.813333 97.962666-2.5088 24.814933-4.932267 49.629867-7.509333 75.605334z m53.4016-33.928534c1.962667-20.906667 3.6352-39.338667 5.4272-57.770666 1.553067-15.906133 3.413333-31.778133 4.727466-47.701334 0.3584-4.283733 1.553067-6.656 5.956267-6.382933 15.616 1.041067 31.709867 0.034133 46.728533 3.652267 36.488533 8.823467 48.725333 54.306133 23.3472 83.029333-15.8208 17.902933-36.7616 23.586133-59.255466 25.088-8.465067 0.546133-17.015467 0.085333-26.9312 0.085333zM512 434.295467c-2.184533-0.648533-3.5328-1.1776-4.932267-1.4336-37.717333-6.877867-75.690667-8.328533-113.646933-2.816-20.974933 3.037867-41.0112 9.489067-57.480533 23.330133-22.9888 19.319467-21.640533 46.848 4.4032 62.0032 13.056 7.594667 28.023467 12.509867 42.5984 17.288533 14.08 4.608 28.996267 6.826667 43.144533 11.264 12.5952 3.925333 14.011733 14.318933 3.584 22.306134-3.345067 2.56-7.441067 5.085867-11.537067 5.751466-11.195733 1.826133-22.698667 4.386133-33.826133 3.566934-24.098133-1.774933-48.042667-5.461333-72.5504-8.430934-1.365333 10.615467-2.935467 23.0912-4.5568 35.9424 4.181333 1.365333 7.68 2.730667 11.264 3.618134 33.9456 8.4992 68.386133 9.608533 102.912 5.12 20.087467-2.6112 39.4752-7.901867 56.695467-19.029334 28.603733-18.4832 36.693333-57.1904-4.676267-75.383466-14.506667-6.382933-30.190933-10.410667-45.482667-15.086934-11.4176-3.4816-23.313067-5.614933-34.525866-9.5232-9.7792-3.413333-11.144533-12.202667-3.037867-18.397866 4.6592-3.549867 10.717867-6.997333 16.384-7.3728a480.853333 480.853333 0 0 1 53.384533-0.853334c15.377067 0.699733 30.651733 3.549867 46.4896 5.5296L512 434.295467z m257.143467 2.048L750.933333 614.2976h54.152534c4.778667-45.636267 9.710933-90.7264 14.062933-135.8848 0.6144-6.365867 2.3552-8.840533 8.686933-9.0112 11.434667-0.273067 22.8864-1.979733 34.286934-1.570133 23.722667 0.853333 42.3936 9.728 38.4 43.264-2.901333 24.2688-5.597867 48.571733-8.2432 72.874666-1.092267 10.069333-1.826133 20.189867-2.730667 30.4128h55.330133c3.584-35.259733 7.9872-70.058667 10.496-104.994133 3.413333-47.4624-17.7664-73.3184-64.682666-80.213333-40.96-6.007467-81.339733-0.341333-121.5488 7.133866z m-483.498667 134.6048c-8.738133 1.297067-16.384 2.798933-24.098133 3.4816-25.6512 2.235733-51.319467 3.9424-76.305067-4.266667-13.909333-4.590933-24.6784-12.578133-29.7984-25.9584-7.901867-20.701867 0.887467-47.104 19.831467-60.3136 17.373867-12.117333 37.717333-15.9232 58.453333-15.9232 22.545067-0.017067 45.090133 2.423467 68.232533 3.84L307.2 432.298667c-15.069867-1.723733-29.4912-3.925333-43.997867-4.9152-41.0112-2.798933-80.64 2.6112-117.469866 20.462933-30.020267 14.557867-52.053333 36.010667-58.6752 68.130133-7.850667 38.144 11.537067 69.495467 51.7632 85.845334 19.1488 7.765333 39.287467 12.509867 60.0064 12.5952 24.746667 0.1024 49.493333-1.570133 74.205866-2.952534 3.106133-0.170667 8.311467-2.901333 8.669867-5.034666 1.979733-11.554133 2.730667-23.278933 3.9424-35.464534z" fill="#DD1700" p-id="6737"></path></svg>'
14.             },
15.             link: 'https://guoqiankun.blog.csdn.net/?type=blog'
16.           },
17.           {
18.             icon: {
19.               svg: '<svg t="1713408687091" class="icon" viewBox="0 0 1316 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="7801" width="64" height="64"><path d="M643.181714 247.698286l154.916572-123.172572L643.181714 0.256 643.072 0l-154.660571 124.269714 154.660571 123.245715 0.109714 0.182857z m0 388.461714h0.109715l399.579428-315.245714-108.361143-87.04-291.218285 229.888h-0.146286l-0.109714 0.146285L351.817143 234.093714l-108.251429 87.04 399.433143 315.136 0.146286-0.146285z m-0.146285 215.552l0.146285-0.146286 534.893715-422.034285 108.397714 87.04-243.309714 192L643.145143 1024 10.422857 525.056 0 516.754286l108.251429-86.893715L643.035429 851.748571z" fill="#1E80FF" p-id="7802"></path></svg>'
20.             },
21.             link: 'https://juejin.cn/user/2409752520033768/posts'
22.           }
23.         ]
24.   }
25. })

复制代码

2.4.2. 页面效果展示

2.5. 豁亮主题展示：appearance

appearance 配置不在 themeConfig 字段里面，而是和 themeConfig 同级

2.5.1. 数据类型

1. boolean | 'dark' | 'force-dark' |

复制代码

默认值为 true
2.5.2. config 配置示例

1. export default defineConfig({
2.   ...,
3.   appearance: false,
4.   ...,
5. })

复制代码

2.5.3. 页面效果展示

当我们设置为 false 的时候，就没有 switch 按钮了
3. 页脚

页脚面配置是 themeConfig.footer 字段
VitePress 将在全局页面底部显示页脚，当侧边栏可见时，不会显示页脚
3.1. footer 字段类型

object

1. export interface Footer {
2.   message?: string
3.   copyright?: string
4. }

复制代码

3.2. themeConfig 配置示例

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   appearance: false,
6.   themeConfig: {
7.     ...,
8.     footer: {
9.       message: 'Released under the MIT License.',
10.       copyright: 'Copyright © 2024-present gqk'
11.     }
12.   }
13. })

复制代码

3.3. 页面效果展示

4. 左侧边栏

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

4.1. 左侧边栏底子配置

4.1.1 创建 md 文件

把项目初始化的除了 index.md 之外的另两个 md 文件删除，再在之前创建的文件夹中创建对应的 xxx1.md 和 xxx2.md 文化，如下：

1. .
2. ├── docs
3. │   ├── api
4. │   │   ├── api1.md
5. │   │   ├── api2.md
6. │   │   └── index.md
7. │   ├── basic
8. │   │   ├── basic1.md
9. │   │   ├── basic2.md
10. │   │   └── index.md
11. │   ├── core
12. │   │   ├── core1.md
13. │   │   ├── core2.md
14. │   │   └── index.md
15. │   ├── summarize
16. │   │   ├── index.md
17. │   │   ├── summarize1.md
18. │   │   └── summarize2.md
19. │   ├── teach
20. │   │   ├── index.md
21. │   │   ├── teach1.md
22. │   │   └── teach2.md
23. │   └── team
24. │       ├── index.md
25. │       ├── team1.md
26. │       └── team2.md

复制代码

4.1.2. 在 themeConfig 中添加 sidebar 字段

1. import { defineConfig } from 'vitepress'
2. export default defineConfig({
3.   title: "My VitePress Demo Project",
4.   description: "This is my VitePress demo project",
5.   appearance: false,
6.   themeConfig: {
7.     ...,
8.     sidebar: [
9.       {
10.         text: '基础篇',
11.         items: [
12.           { text: '基础篇', link: '/basic/index' },
13.           { text: '基础篇1', link: '/basic/basic1' },
14.           { text: '基础篇2', link: '/basic/basic2' }
15.         ]
16.       },
17.       {
18.         text: 'API 篇',
19.         items: [
20.           { text: 'API篇', link: '/api/index' },
21.           { text: 'API篇1', link: '/api/api1' },
22.           { text: 'API篇2', link: '/api/api2' }
23.         ]
24.       },
25.       {
26.         text: '核心篇',
27.         items: [
28.           { text: '核心篇', link: '/core/index' },
29.           { text: '核心篇1', link: '/core/core1' },
30.           { text: '核心篇2', link: '/core/core2' }
31.         ]
32.       },
33.       {
34.         text: '教学篇',
35.         items: [
36.           { text: '教学篇', link: '/teach/index' },
37.           { text: '教学篇1', link: '/teach/teach1' },
38.           { text: '教学篇2', link: '/teach/teach2' }
39.         ]
40.       },
41.       {
42.         text: '总结篇',
43.         items: [
44.           { text: '总结篇', link: '/summarize/index' },
45.           { text: '总结篇', link: '/summarize/summarize1' },
46.           { text: '总结篇', link: '/summarize/summarize2' }
47.         ]
48.       },
49.       {
50.         text: '团队篇',
51.         items: [
52.           { text: '团队篇', link: '/team/index' },
53.           { text: '团队篇', link: '/team/team1' },
54.           { text: '团队篇', link: '/team/team2' }
55.         ]
56.       }
57.     ],
58.   }
59. })

复制代码

4.1.3. 页面效果展示

4.1.4. 配置注意项

• 基本用法是传入一个数组，text 是侧边栏名词，link 是链接
  
• 每个 link 都是以 / 开头，而且不须要加 /docs，直接以 docs/index.md 文件配置相对路径
  
• 不须要加 .md 后缀
  
• items 可以嵌套，最多嵌入 6 级深度，超过将被忽略，且不会显示
  

4.2. 多左侧边栏

许多时候我们须要根据不同的路径显示不同的侧边栏
好比：我想把底子篇、API 篇、焦点篇用同一个侧边栏，教学篇、总结篇、团队篇用同一个侧边栏
4.2.1. 新建 utils.ts 文件

在 config.mts 同级创建 utils.ts 文件

1. docs/.vitepress
2. ├── config.mts
3. └── utils.ts

复制代码

4.2.2. 写入一下代码

1. /**
2. * @param {string} pathname pathname 值
3. * @returns {SidebarItem[]} 侧边栏数组
4. */
5. export const getSideBarList = (pathname: string) => {
6.   if (['/basic', '/core', '/api'].includes(pathname)) {
7.     return [
8.       {
9.         text: '基础篇',
10.         items: [
11.           { text: '基础篇', link: '/basic/index' },
12.           { text: '基础篇1', link: '/basic/basic1' },
13.           { text: '基础篇2', link: '/basic/basic2' }
14.         ]
15.       },
16.       {
17.         text: 'API 篇',
18.         items: [
19.           { text: 'API篇', link: '/api/index' },
20.           { text: 'API篇1', link: '/api/api1' },
21.           { text: 'API篇2', link: '/api/api2' }
22.         ]
23.       },
24.       {
25.         text: '核心篇',
26.         items: [
27.           { text: '核心篇', link: '/core/index' },
28.           { text: '核心篇1', link: '/core/core1' },
29.           { text: '核心篇2', link: '/core/core2' }
30.         ]
31.       }
32.     ]
33.   }
34.   return [
35.     {
36.       text: '教学篇',
37.       items: [
38.         { text: '教学篇', link: '/teach/index' },
39.         { text: '教学篇1', link: '/teach/teach1' },
40.         { text: '教学篇2', link: '/teach/teach2' }
41.       ]
42.     },
43.     {
44.       text: '总结篇',
45.       items: [
46.         { text: '总结篇', link: '/summarize/index' },
47.         { text: '总结篇1', link: '/summarize/summarize1' },
48.         { text: '总结篇2', link: '/summarize/summarize2' }
49.       ]
50.     },
51.     {
52.       text: '团队篇',
53.       items: [
54.         { text: '团队篇', link: '/team/index' },
55.         { text: '团队篇1', link: '/team/team1' },
56.         { text: '团队篇2', link: '/team/team2' }
57.       ]
58.     }
59.   ]
60. }

复制代码

4.2.3. 在 config.mts 中引入

1. import { defineConfig } from 'vitepress'
2. import { getSideBarList } from './utils' // 引入 getSideBarList 方法
3. export default defineConfig({
4.   title: "My VitePress Demo Project",
5.   description: "This is my VitePress demo project",
6.   appearance: false,
7.   themeConfig: {
8.     ...,
9.     sidebar: {
10.       '/basic/': getSideBarList('/basic'),
11.       '/api/': getSideBarList('/api'),
12.       '/core/': getSideBarList('/core'),
13.       '/teach/': getSideBarList('/teach'),
14.       '/summarize/': getSideBarList('/summarize'),
15.       '/team/': getSideBarList('/team'),
16.     }
17.   }
18. })

复制代码

4.2.4. 页面效果展示

4.2.5. 配置注意项

• 多侧边栏配置时， sidebar 为对象
  
• key 的值为 /basic/、/basic、basic 都可以，但是建议以 /basic/ 为 key
  

4.3. 可折叠侧边栏：collapsed

默认情况下，全部的侧边栏都是展开显示的，可以设置 collapsed 来控制展开和隐蔽
4.3.1. sidebar 配置

1. [
2.   {
3.     text: '基础篇',
4.     collapsed: false,
5.     items: [
6.       { text: '基础篇', link: '/basic/index' },
7.       { text: '基础篇1', link: '/basic/basic1' },
8.       { text: '基础篇2', link: '/basic/basic2' }
9.     ]
10.   },
11.   {
12.     text: 'API 篇',
13.     collapsed: true,
14.     items: [
15.       { text: 'API篇', link: '/api/index' },
16.       { text: 'API篇1', link: '/api/api1' },
17.       { text: 'API篇2', link: '/api/api2' }
18.     ]
19.   },
20.   {
21.     text: '核心篇',
22.     collapsed: false,
23.     items: [
24.       { text: '核心篇', link: '/core/index' },
25.       { text: '核心篇1', link: '/core/core1' },
26.       { text: '核心篇2', link: '/core/core2' }
27.     ]
28.   }
29. ]

复制代码

4.3.2. 页面效果展示

5. 右侧边栏

   右侧边栏是大纲中显示的标题导航块
  配置 outline 字段可以设置渲染大纲层级

5.1. 在 basic 中的 index.md 写入以下内容

1. # BASIC
3. BASIC index page
5. ## 标题1
7. 标题1 描述
9. ### 标题1小标题1
10. 标题1小标题1 描述
12. #### 小小标题1
13. 小小标题1 描述
15. ##### 5级标题1
16. 5级标题 描述
18. ###### 6级标题1
19. 6级标题 描述
21. ###### 6级标题1
22. 6级标题 描述
24. ##### 5级标题2
25. 5级标题 描述
27. ###### 6级标题1
28. 6级标题 描述
30. ###### 6级标题1
31. 6级标题 描述
33. #### 小小标题2
34. 小小标题2 描述
36. ### 标题1小标题2
37. 标题1小标题2 描述
39. #### 小小标题1
40. 小小标题1 描述
42. #### 小小标题2
43. 小小标题2 描述
45. ##### 5级标题1
46. 5级标题 描述
48. ###### 6级标题1
49. 6级标题 描述
51. ###### 6级标题1
52. 6级标题 描述
54. ##### 5级标题2
55. 5级标题 描述
57. ###### 6级标题1
58. 6级标题 描述
60. ###### 6级标题1
61. 6级标题 描述
63. ### 标题1小标题3
64. 标题1小标题3 描述
66. #### 小小标题1
67. 小小标题1 描述
69. #### 小小标题2
70. 小小标题2 描述
72. ## 标题2
74. 标题2 描述
76. ### 标题2小标题1
77. 标题2小标题1 描述
79. ### 标题2小标题2
80. 标题2小标题2 描述
82. ### 标题2小标题3
83. 标题2小标题3 描述

复制代码

右侧边栏效果展示

可以看出只展示了 h2 标题，outline 的默认值为 2
5.2. 在 themeConfig 中添加 outline 字段

5.2.1. false 值

没有 true 类型，只有 false，设置 false 时不展示右侧边栏
5.2.2. 单个数值

1. export default defineConfig({
2.   themeConfig: {
3.     ...,
4.     outline: 3,
5.   }
6. })

复制代码

只展示 h3 标题

5.2.3. deep 字段

当为字符串时，只有 deep 一个字段，与 [2, 6] 雷同，展示 h2~h6 全部标题

5.2.4. 数组形式

1. export default defineConfig({
2.   themeConfig: {
3.     ...,
4.     outline: [2,5],
5.   }
6. })

复制代码

展示 h2~h5 的标题

5.2.5. 对象形式

1. export default defineConfig({
2.   themeConfig: {
3.     ...,
4.     outline: {
5.       level: [2,4],
6.       label: '当前页'
7.     },
8.   }
9. })

复制代码

当是对象形式的时候，有 level 和 label 两个字段

• level: number | [number, number] | 'deep'，是展示标题品级
  
• label: string，是 outline 的标题，更换 On this page 文案
  

5.3. 在当前页面中覆盖 config.mts 中的配置

在 basic/index.md 文件顶部写入以下内容

1. ---
2. outline: 'deep'
3. ---

复制代码

1. ---
2. outline:
3.   level: [1,3]
4. ---

复制代码

在当前页面的 outline 中配置 label 不生效，还是会用到 config 中的配置或者默认值
5.4. 展示在页面内容左边

将 aside 设置为 left

1. ---
2. outline:
3.   level: [1,3]
4.   label: 基础篇
5. aside: left
6. ---

复制代码

6. 上一页&下一页

   可以自界说上一页和下一页的文本和链接
  假如在 xx.md 文件中不指定上一页和下一页的话，vitePress 会从侧边栏配置中推断
6.1. 类型

1. string | false | { text?: string; link?: string }

复制代码

6.2. 页面配置

在对应的 md 文件顶部添加以下内容

1. ---
2. prev:
3.   text: '团队篇2'
4.   link: '/team/team2'
5. next:
6.   text: '教学篇'
7.   link: '/teach/index'
8. ---

复制代码

6.3. 页面效果展示

7. 配置项目 head

head 模块配置的内容会添加在项目标 head 标签中，在 config 中配置
7.1. 数据类型

1. type HeadConfig =
2.   | [string, Record<string, string>]
3.   | [string, Record<string, string>, string]

复制代码

7.2. 添加 favicon

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   head: [
6.     ['link', { rel: 'icon', href: '/extension.ico'}]
7.   ],
8.   themeConfig: {
9.         ...
10.   }
11. })

复制代码

7.3. 添加字体

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   head: [
6.     ['link', { rel: 'icon', href: '/extension.ico'}],
7.     ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }]
8.   ],
9.   themeConfig: {
10.         ...
11.   }
12. })

复制代码

7.4. 添加 CSS 文件

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   head: [
6.     ['link', { rel: 'icon', href: '/extension.ico'}],
7.     ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
8.     ['link', { rel: 'stylesheet', href: 'https://xxx.com/static/layui/css/layui.css' }],
9.   ],
10.   themeConfig: {
11.         ...
12.   }
13. })

复制代码

7.5. 添加 JS 文件

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   head: [
6.     ['link', { rel: 'icon', href: '/extension.ico'}],
7.     ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
8.     ['link', { rel: 'stylesheet', href: 'https://xxx.com/static/layui/css/layui.css' }],
9.     ['script', { src: 'https://xxx.com/sdk.js'}]
10.   ],
11.   themeConfig: {
12.         ...
13.   }
14. })

复制代码

7.6. 添加 JS 代码

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   head: [
6.     ['link', { rel: 'icon', href: '/extension.ico'}],
7.     ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
8.     ['link', { rel: 'stylesheet', href: 'https://xxx.com/static/layui/css/layui.css' }],
9.     ['script', { src: 'https://xxx.com/sdk.js'}],
10.     ['script', {}, `
11.       console.log('window', window);
12.       console.log('document', document);
13.       `
14.     ]
15.   ],
16.   themeConfig: {
17.         ...
18.   }
19. })

复制代码

7.7. 最终渲染

8. 删除 URL 中的 .html 后缀

config 中配置 cleanUrls 为 true
类型：boolean

1. export default defineConfig({
2.   title: "My VitePress Demo Project",
3.   description: "This is my VitePress demo project",
4.   appearance: false,
5.   cleanUrls: true,
6.   ...
7. })

复制代码

9. 图片资源

9.1. 图片直接放在 public 文件夹中

假如图片直接放在 public 文件夹中，在项目中使用的话，直接 /xxx.png 即可，VitePress 会自处理
9.2. 在 public 文件中创建对应模块的文件夹

偶然候图片资源太多，想分类整理，那就在 public 中创建对应模块的文件夹，把当前模块的资源放在对应的文件夹中。

1. docs/public/basic
2. ├── basic-desc.png
3. └── basic-popup.png

复制代码

9.2.1. 开发引入图片 ❌

1. 

复制代码

在开发的时候，你发现直接写图片名称也可以显示图片，这个时候你很高兴
9.2.2. build 项目

1. pnpm run docs:build

复制代码

当你辛辛苦苦开发完成，build 项目时，发现报错了…

以是你不能直接写图片名称，哪怕它能精确显示
9.2.3. 精确引入图片✅

要把文件夹的名称加上

1. 

复制代码

四、项目摆设到 github

1. 新建 github 项目

2. 构建 VitePress 项目

2.1. 设置 config 中的 base

由于我们的项目名称为 vite-press-demo，以是我们把 base 设置为 /vite-press-demo/，需注意前后 /

1. export default defineConfig({
2.   base: '/vite-press-demo/',
3.   ...,
4. })

复制代码

2.2. 页面显示非常

这个时候你发现当地页面显示非常

是因为配置了 base 之后，导致路径不精确，点击上面的链接即可

2.3. favicon 显示非常

配置好 base 之后，你发现其他页面都没题目，图片也都能正常显示，但是 favicon 不能正常显示。

只须要把 head 中配置的 icon 路径改下即可，加上 /vite-press-demo 前缀

1. head: [
2.     ['link', { rel: 'icon', href: '/vite-press-demo/extension.ico'}],
3. ], // 加上 /vite-press-demo 前缀

复制代码

2.4. 运行 pnpm run docs:build
举行项目构建

项目正常构建成功

3. 项目发布到 github 上

3.1. clone 项目，并把构建的内容发布到 main 分支

是构建之后 dist 文件夹中的内容，不包罗 dist 文件夹

1. .
2. ├── 404.html
3. ├── README.md
4. ├── api
5. ├── assets
6. ├── basic
7. ├── components
8. ├── core
9. ├── develop.svg
10. ├── ext-2.svg
11. ├── ext.svg
12. ├── extension.ico
13. ├── hashmap.json
14. ├── index.html
15. ├── react.svg
16. ├── summarize
17. ├── teach
18. ├── team
19. ├── tj.svg
20. └── vue.svg

复制代码

3.2. 摆设到 github

3.2.1. 点击 Setting 按钮

3.2.2. 点击 Pages 按钮

3.2.3. 找到 Branch，并下拉选择 main 分支

3.2.4. 点击 Save 保存

3.2.5. 等…

等几分钟，一般一分钟以内
不绝的革新当前页面也行
然后就会发现当前页面多了个 Visit site 模块

3.2.6. 点击 Visit site

点击之后，就跳转到对应的网站链接啦…
我这边是这个：https://18055975947.github.io/vite-press-demo/

4. 更新项目

当文档内容须要更新的时候，在开发完成之后，重新构建完成，把 dist 文件夹中内容重新发布到 main 分支即可，剩下的就是等就行
也可以点击 Setting-> Pages 模块革新页面
可以看到这下面有摆设的时间点

五、总结

1. 项目目录

1. .
2. ├── docs
3. │   ├── .vitepress
4. │   │   ├── config.mts
5. │   │   └── utils.ts
6. │   ├── api
7. │   │   ├── api1.md
8. │   │   ├── api2.md
9. │   │   └── index.md
10. │   ├── basic
11. │   │   ├── basic1.md
12. │   │   ├── basic2.md
13. │   │   └── index.md
14. │   ├── components
15. │   │   └── test.md
16. │   ├── core
17. │   │   ├── core1.md
18. │   │   ├── core2.md
19. │   │   └── index.md
20. │   ├── index.md
21. │   ├── public
22. │   │   ├── basic
23. │   │   │   ├── basic-desc.png
24. │   │   │   └── basic-popup.png
25. │   │   ├── develop.svg
26. │   │   ├── ext-2.svg
27. │   │   ├── ext.svg
28. │   │   ├── extension.ico
29. │   │   ├── react.svg
30. │   │   ├── tj.svg
31. │   │   └── vue.svg
32. │   ├── summarize
33. │   │   ├── index.md
34. │   │   ├── summarize1.md
35. │   │   └── summarize2.md
36. │   ├── teach
37. │   │   ├── index.md
38. │   │   ├── teach1.md
39. │   │   └── teach2.md
40. │   └── team
41. │       ├── index.md
42. │       ├── team1.md
43. │       └── team2.md
44. ├── package.json
45. └── pnpm-lock.yaml

复制代码

2. 项目代码

源码：【develop 分支】
Demo 预览：【demo 项目预览】
3. 结束语

• 到这整个 vitePress 构建博客并摆设到 github 就基本结束了
  
• 还差一些自界说主题的内容，这个后面偶然间再说
  
• 假如有题目可以在掘金、CSDN 或者 github 上找我，看到都会复兴
  
• 希望能资助到各人
  
• 
  
  
  
  

  ---

  欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/)

  Powered by Discuz! X3.4