Vitepress项目文档快速搭建指南_vitepress搭建

简介

官网介绍：Vitepress 是一款简单高校的 SSG+SPA 框架

简单的来讲，我们将会利用 vitepress 框架来快速搭建我们的项目文档（或者做个人博客使用）

安装

首先新建一个文件夹作为项目的根目录，称为 vitepress-starter

进入该目录，使用 npm 初始化 package.json
npm init -y

安装 vue 以及 vitepress 依赖
npm install -D vitepress vue

然后打开 package.json 修改启动参数

"scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
1
2
3
4
5

最后最后，在 vitepress-starter 文件夹下新建一个 docs 文件夹，作为所有主体文件的存放处

额外依赖

额外依赖即该项目中可有可无的依赖

Algolia DocSearch 搜索支持：安装该依赖后，将可以在文档中启用搜索功能
npm install @docsearch/js@3

carbonads 广告支持：通过该依赖将可以直接在项目文档内部插入广告

项目结构与路径分析

基础指南搭建完成后的项目结构（这里是 docs 文件夹下的内容）

│  index.md
│
├─.vitepress
│  │  config.js
│  │
│  ├─cache
│  │  └─deps
│  │          package.json
│  │          vue.js
│  │          vue.js.map
│  │          _metadata.json
│  │
│  └─theme
│          index.js
│
├─document
│      index.md
│
├─public
│  └─icons
│          car.svg
│
└─starter
        starter-configuration.md
        starter-install.md
        starter-uninstall.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

这是主要文件夹的功能分析：

1. .vitepress 主要处理全局配置以及自定义主题
2. document&starter 我们自定义的两个文章主题，在里面写入 markdown 文件
3. public 静态资源存放

几个注意事项

根目录下必须定义一个 index.md 作为起始页
其余子目录（如 document）就不需要定义 index.md 了

如果一个目录下定义了 index.md，则对应 URL 无需精确到文件名即可自动转到
譬如 starter 文件夹下定义了 index.md，则对应的 URL 为：/starter/或者/starter/index

一般的，建议所有需要填写路径的地方，开头最好都有一个 / 符号

再不做任何配置的情况下，默认就是以 docs 作为整个项目路径索引的根目录
比如 public 文件夹就可以表示为 /public

frontmatter

所谓 frontmatter 即在 markdown 文件头部添加的一个 yaml 字段，他一般可用于配置 markdown 文件

vitepress 支持三种格式的布局，不同布局对应不同特性

1. doc 布局：基础文档布局，一般的 markdown 文件都使用该头部字段
2. page 布局：自定义页面用的
3. home 布局：起始页布局，一般特定用在根目录下的 index.md，将其作为起始页使用

譬如下方，我们就为当前的 markdown 文件指定了布局类型 doc

---
layout:doc
---

### helloworld

helloworld
1
2
3
4
5
6
7

home 布局

被定义为 home 布局的文件最好不要再额外多写内容了，所有的内容都写在 yaml 头里面！
所以可见下方 index.md 代码仅包含了一个 frontmatter

将根目录下的 index.md 文件全部内容删除并替换为以下内容

---
# 定义布局为home
layout: home

#
hero:
  name: ZerNote
  text: An online note-taking system
  tagline: 简洁高效的多人在线协作笔记系统
  image:
    src: /public/icons/car.svg
    alt: VitePress
  actions:
    - theme: brand
      text: 快速上手
      link: /guide/what-is-vitepress
    - theme: alt
      text: 查看Github源码
      link: https://github.com/vuejs/vitepress

features:
  - icon: 
声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/酷酷是懒虫/article/detail/841325