前言

使用主题的一些总结，并非完整的教程，如果看完整的教程，请去 Vdoing 官网

• 主题介绍
• 获取途径
• 目录结构
• 使用过程
• 级别说明
• 创建文档
• Front Matter
• 碎片化文档

主题介绍

本站使用的主题是 Vdoing (opens new window)，它是一款简洁高效的 VuePress 知识管理&博客主题，初衷是打造一个好用的、面向程序员的知识管理工具。

主题千千万，我选择这个主题的原因之一是因为它对于文档的命名约定要求非常符合我的想法，即要有两位序号，分清楚顺序，从 00 或 01 开始累计，如 01.文件夹、02.文件.md。如果日后进行文档的梳理也是非常方便的，一眼望去，结构明了。

获取途径

这里是主题的获取途径。

途径一：主题作者的源代码 GitHub 地址：点击跳转 (opens new window)。

途径二：主题官网提供的命令下载：

# 克隆项目，也就是下载项目到本地
git clone https://github.com/xugaoyi/vuepress-theme-vdoing.git

# 进入项目的根目录下
cd vuepress-theme-vdoing

# 安装项目需要的依赖包
npm install # or yarn install

# 启动项目
npm run dev # or yarn dev

# 克隆项目，也就是下载项目到本地
git clone https://github.com/xugaoyi/vuepress-theme-vdoing-doc.git

# 进入项目的根目录下
cd vuepress-theme-vdoing-doc

# 安装项目需要的依赖包
npm install # or yarn install

# 启动项目
run dev # or yarn dev

// Make sure to add code blocks to your code group

知识库兼博客风格预设配置：指的是主题作者自己的博客项目内容，也就是作者正在用的博客。

文档风格预设配置：指的是该主题的基本配置项目，不包含作者个人的最新文章更新。

途径三：前往使用该主题的博主 GitHub 地址进行克隆(下载)到本地，如我的地址：跳转地址 (opens new window)。

目录结构

通过获取途径获取到了主题的代码时，它的结构大致如下：

知识库兼博客风格预设配置目录结构：

.
├── .github   (可选，GitHub Actions 所需文件)
│   ├── workflows
│   │   ├── baiduPush.yml (可选，百度定时自动推送)
│   │   └── ci.yml (可选，自动部署)
├── docs (必须，不要修改文件夹名称)
│   ├── .vuepress （同官方，查看：https://vuepress.vuejs.org/zh/guide/directory-structure.html#目录结构）
│   ├── @pages (可选，自动生成的文件夹，存放分类页、标签页、归档页)
│   ├── _posts (可选，专门存放碎片化博客文章的文件夹)
│   ├── <结构化目录>
│   └── index.md (首页)
├── theme-vdoing (可选，本地的vdoing主题)
├── utils  (可选，vdoing主题使用的node工具)
│   ├── modules
│   ├── config.yml (可选，批量操作front matter配置)
│   ├── editFrontmatter.js (可选，批量操作front matter工具)
├── baiduPush.sh (可选，百度推送命令脚本)
├── deploy.sh (可选，部署命令脚本)
│
└── package.json

结构说明

• docs 文件夹名称请不要修改
• docs/.vuepress 用于存放全局的配置、样式、静态资源等，同官方，查看 详情(opens new window) (opens new window)
• docs/@pages 此文件夹是自动生成的，存放分类页、标签页、归档页对应的.md文件，一般不需要改动
• docs/_posts 专门用于存放碎片化博客文章，里面的.md文件不需要遵循命名约定，不会生成结构化侧边栏和目录页。
• docs/<结构化目录> 请查看《构建结构化站点的核心配置和约定》 (opens new window)。
• docs/index.md 首页
• theme-vdoing 存放在本地的vdoing主题文件，如果你想深度的修改主题，首先要在docs/.vuepress/config.js中配置使用的主题指向这个文件。

文档风格预设配置目录结构：

.
├── .github   (可选，GitHub Actions 所需文件)
│   ├── workflows
│   │   └── ci.yml (可选，自动部署)
├── docs (必须，不要修改文件夹名称)
│   ├── .vuepress （同官方，查看：https://vuepress.vuejs.org/zh/guide/directory-structure.html#目录结构）
│   ├── @pages (可选，自动生成的文件夹，存放分类页、标签页、归档页)
│   ├── _posts (可选，专门存放碎片化博客文章的文件夹)
│   ├── <结构化目录>
│   └── index.md (首页)
├── utils  (可选，vdoing主题使用的node工具)
│   ├── modules
│   ├── config.yml (可选，批量操作front matter配置)
│   ├── editFrontmatter.js (可选，批量操作front matter工具)
├── deploy.sh (可选，部署命令脚本)
│—— base.js (可选，指定部署项目根目录)
└── package.json

使用过程

• 获取项目后，首先建议先把 .github/workflows/baiduPush.yml 去掉，这是百度推送相关的，部署时不填入自己的百度信息会报错，后期需要再加入

• 打开 docs/.vuepress/config 目录下的 themeConfig.js 文件，滑到最下方，把 htmlModules 注释掉，这是首页右下方的广告：二维码广告

• 如果不使用本地的 Vdoing 主题，把 theme-vdoing 去掉。theme-vdoing 目录下，可以修改很多的主题样式等，但是使用本地主题就等于放弃了后续的升级服务，所以建议去掉这个。用「在线」的官网主题，即默认

• 因为主题已经配置了很多的内容，所以大部分是不需要自己修改的，建议去 .vuepress 目录下把一些 .js 文件看下，都有注释讲解，里面也有个人信息的配置，以及个性签名，页面的背景图等配置。先启动项目，再看注释配合页面，理解的效果更佳

• 如果想修改首页的上方的背景图，主题默认是黑色栅格背景，请打开 docs/index.md 文档，在 features 同级下加入 bannerBg 属性，这个属性就是配置背景图，如 bannerBg: /img/index/bg.jpg 代表 docs/.vuepress/public/img/index 下的 bg.jpg 图片

• 如果想修改首页的整个大背景图，打开 themeConfig.js 文件，找到被注释的 bodyBgImg 和 bodyBgImgOpacity，并在前者加入大背景图的图片路径，他会覆盖首页上方的背景图，使其失效。后者是大背景图的透明度，范围：0-1

• 如果目录页不想扫描到本身的文档(目录页文档)，则放到专门存放目录页的目录如 00.目录页 下

• 不一定按照导航栏创建文件夹目录，如我的导航栏中，框架下的微服务目录，就是和框架目录同级别，为了不让导航栏那么广，所以放在了框架导航栏里面

• @Pages 目录下三个文档是主题自带的三个功能，删除任意一个文档，都会导致该文档的 url 链接无法访问，如果不需要某个功能，可以删除

• 需要稍微修改主题的样式，打开 docs/.vuepress/styles/index.styl 文件进行样式添加

级别说明

源目录（一般是docs）底下的级别现在我们称之为一级目录，一级目录的下一级为二级目录，以此类推，最多到四级目录。

• 一级目录
  1. .vuepress、@pages、_posts、index.md 或 README.md 这些文件(文件夹)不参与数据生成。
  2. 序号非必须。（如一些专栏，可以不用序号)
• 二级目录
  1. 该级别下可以同时放文件夹和.md文件，但是两者序号要连贯（参考下面的例子）。
  2. 必须有序号
• 三级目录
  • (同上)
• 四级目录v1.6.0 +
  1. 该级别下只能放.md文件。
  2. 必须有序号

所有级别内至少有一个文件或文件夹。

.
├── docs
│   │  (不参与数据生成)
│   ├── .vuepress
│   ├── @pages
│   ├── _posts
│   ├── index.md
│   │
│   │ (以下部分参与数据生成)
│   ├── 《JavaScript教程》专栏 (一级目录)
│   │   ├── 01.章节1 (二级目录)
│   │   |   ├── 01.js1.md (三级目录-文件)
│   │   |   ├── 02.js2.md
│   │   |   └── 03.js3.md
│   │   └── 02.章节2 (二级目录)
│   │   |   ├── 01.jsa.md
│   │   |   ├── 02.小节 (三级目录)
│   │   |   |   └── 01.jsxx.md (四级目录-文件)
│   ├── 01.前端
│   │   ├── 01.JavaScript
│   │   |   ├── 01.js1.md
│   │   |   ├── 02.js2.md
│   │   |   └── 03.js3.md
│   │   └── 02.vue
│   │   |   ├── 01.vue1.md
│   │   |   └── 02.vue2.md
│   ├── 02.其他
│   │   ├── 01.学习
│   │   |   ├── 01.xxa.md
│   │   |   └── 02.xxb.md
│   │   ├── 02.学习笔记
│   │   |   ├── 01.xxa.md
│   │   |   └── 02.xxb.md
│   │   ├── 03.文件x.md
│   │   └── 04.文件xx.md
│   └── 03.关于我
│   │   └── 01.关于我.md
.   .

创建文档

创建文档必须按照级别说明的约定，比如想创建 Java 的知识体系文档，则在 docs 下创建一级目录，名为 01.Java，再进入 01.Java 目录，创建两个二级目录，分别名为 01.Java基础、02.Java进阶，接着进入 01.Java基础 目录，创建文档 01.Java入门.md。依次类推。

注意：一个目录下的文件不能出现相同序号

启动项目时，会根据序号顺序在侧边栏进行排序，最小的在最上方

建议序号要有间隔，如00、05、10、15，方便日后在中间插入新的文档。

Front Matter

front matter 指的是 markdown 文档最上方的一些 yaml 配置，在主题下 front matter 有更多的参数配置。

提供三个模板：（记得去掉注释）

---
pageComponent: 
  name: Catalogue   # 目录页必须为 Catalogue
  data: 
    path: 01.java # 扫描文档的目录路径，直接指定 docs 下的目录，无需有 / 开头
    imgUrl: /   # 目录页标题旁边的图片，开头必须有 /：代表.vupress的public目录
    description: # 目录页的描述 
title: 本站 - 主题 # 目录页的标题
date: 2021-11-07 21:15:53  # 文章页生成时间
permalink: /     # 指定 url 跳转地址，跳转到该url，就获取该文档内容
sidebar: false     # 是否生成侧边栏，默认为 true
article: false		# 是否为文章页，默认为 true，下方有说明
comment: false		# 是否生成评论区，默认为 true
editLink: false		# 是否可以编辑，默认为 true
---

---
title: 本站 - 主题 # 文章页标题
date: 2021-11-07 21:15:53  # 文章页生成时间
permalink: /  # 指定 url 跳转地址，点击该url，获取该文档内容
categories:
  -   # 文章目录，在首页的文章分类出现
tags: 
  -    # 标签，在首页的热门标签出现
---

---
title: 本站 - 主题 # 文章页标题
date: 2021-11-07 21:15:53  # 文章页生成时间
permalink: /  # 指定 url 跳转地址，点击该url，获取该文档内容
article: false	# 是否为文章页，默认为 true，下方有说明
categories:
  -   # 文章目录，在首页的文章分类出现
tags: 
  -    # 标签，在首页的热门标签出现
---

// Make sure to add code blocks to your code group

目录页：自动扫描 path 的路径下的文档，生成目录，此时你点击我的 Java 导航，弹出的就是目录页，如果不想自身被扫描到，请放到专门存放目录页的目录如 00.目录页 下

文章页：有内容、个人信息，文档目录信息、日期、面包屑的文档，此时看的内容就是文章页，为了区别目录页。不加sidebar、article、comment、editLink 是因为默认为 true。

非文章页非目录页：一般用于友情连接，转载连接等不包含个人信息的页面，并且不存入归档时间线内，以及首页下方的更新目录中。

面包屑：文档所在的路径。滑到最上方，如果看到 关于/关于 - 本站，这就是面包屑，代表该文档的一级目录为关于，二级目录也就是文档名为关于 - 本站。

特别说明：

article 为 false 时，则是非文章页非目录页。默认为 true。

例子1：滑到最上方，如果看到 关于/关于 - 本站、Young Kbt、2021-11-07，则代表这是文章页，即 article 为 true。

例子2：打开更多导航的友情链接，这是一个非文章页非目录页，代表 article 为false。

例子3：点击 Java 导航，弹出的页面就是目录页。

碎片化文档

碎片化文档是放在 _posts 目录下，比如主题自带的随笔。特点：

• 不遵守命名约定，即不需要有序号前缀
• 无法通过导航栏进行跳转，只能通过首页的文章分类或者热门标签进行查看。或者 url 地址直接跳转
• 没有面包屑功能
• 侧边栏只有自己的大纲标题，无法扫描目录下的其他文档
• 不构成体系化。记录零碎的生活痕迹、技术感想都可以用到碎片化文档

笔记

部分内容摘录于 Vdoing 主题官网

2021-11-07 @Young Kbt