道破——VuePress

发表于： 分类于：
字数：1472 阅读：≈ 3分钟 浏览：

1. 开始

1.1. 准备环境

  1. VuePress v2.0.0-beta.49

  2. Nodejs 18.7.0 (npm 8.15.0)

  3. Yarn 1.22.19

  4. yrm 1.0.6

下载Nodejs 对应版本并安装。

安装yarn

1

npm install -g yarn --registry=https://registry.npm.taobao.org

安装yrm并指定淘宝源

1
2
3

npm install -g yrm --registry=https://registry.npm.taobao.org
yrm ls
yrm use taobao

这里注意yarn版本不要升级，使用默认v1版本就行，升到v3版本会使VuePress出现不可预料的错误。

1.2. 快速使用

  1. 创建生成器目录
1
2

mkdir vuepress-starter
cd vuepress-starter
  1. 初始化项目
1
2

git init
yarn init
  1. 安装VuePress为本地依赖
1

yarn add -D vuepress@next
  1. 添加scripts到根目录下package.json中
1
2
3
4
5
6

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  1. 配置.gitignore以忽略缓存目录和临时目录
1
2
3

echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore
  1. 创建第一篇文档
1
2

mkdir docs
echo '# Hello VuePress' > docs/README.md
  1. 启动本地服务器
1

yarn docs:dev
  1. 访问 本地网站http://localhost:8080

1.3. 简单配置

整个vue.js框架的配置策略就是遵循“约定大于配置”，所以在直接上手使用而不是自行扩展代码的情况下，去官方文档读懂配置项就能玩转框架。

创建一个.vuepress目录并新建一个config.js文件，目录结构如下：

1
2
3
4
5
6
7

vuepress-starter（根目录）
├─ docs（文档目录）
│  ├─ .vuepress（配置文件目录）
│  │  └─ config.js（vuepress配置文件）
│  └─ README.md（首页）
├─ .gitignore（git忽略配置文件）
└─ package.json（项目配置）

配置config.js内容

1
2
3
4
5

module.exports = {
  lang: 'zh-CN',
  title: '你好， VuePress ！',
  description: '这是我的第一个 VuePress 站点',
}

1.4. 路由映射

我们再把目录结构拿出来看看，这次我新建了几个文档和目录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

vuepress-starter
├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  ├─ README.md（首页）
│  ├─ Category.md（归档页面）
│  ├─ devtool（我自己建的**开发工具**文档目录）
│  │  └─ vuepress.md（这篇文档的md源文件）
│  └─ other（其他**未分类**文档目录）
│     └─ index.md（其他目录的首页）
│     └─ about.md（关于）
├─ .gitignore
└─ package.json

也就是说默认README.md和index.md都会转为其目录下的index.html文件用以访问，然而，如果你想同时保留这两个文件，就可能会造成冲突。

相对路径路由路径
/README.md/
/index.md/
/category.md/category.html
/other/index.md/other/
/other/about.md/other/about.html

1.5. Frontmatter

Markdown的具体规范详见 道破——Markdown 即可。

Markdown文件可以包含一个YAML Frontmatter。

Frontmatter必须在Markdown文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例：

1
2
3
4
5
6
7
8

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

# 开始
...

你肯定注意到Frontmatter中的字段和配置文件中的站点配置十分类似。

你可以通过Frontmatter来覆盖当前页面的lang, title, description等属性。

因此，你可以把Frontmatter当作页面级作用域的配置。

2. 配置和放弃

当我大致读了一遍官方配置之后，发现功能插件和主题样式特别少，官方支持的主题只有一个默认主题。

我又去官方推荐的 awesome-vuepress 试用了每个第三方主题，遗憾的是，一共七个主题我试了五个，没有一个能让我快乐地成功启动。

到社区寻找答案，发现vuepress-v2的版本属于测试版，而第三方主题并不支持v2，有些作者的版本更新滞后，作者不再维护；有些作者的戾气太重，跟提问者对线。版本管理混乱，不同版本的包引用冲突不断，导致很多不同的严重错误解决不完。

所以对于vuepress的探索到此为止，作为一个文档生成器是合格的，但对我的需求是不符的。

3. 参考

VuePress

Yarn

yrm – Yarn Registry Manager

awesome-vuepress