如何使用 VuePress2

1、VuePress 概述

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown 在新窗口打开来书写内容（如文档、博客等），然后 VuePress 会帮助你生成一个静态网站来展示它们。

VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求，但是现在它已经在帮助大量用户构建他们的文档、博客和其他静态网站。

2、环境及管理工具

TLS版本: node.js 大于 18

依赖管理工具：npm、yarm、mnpm

使用 npm 安装 yarn

npm install -g yarn

3、VuePress 搭建

3.1 创建项目目录

mkdir pressProject
cd pressProject

3.2 初始化项目

yarn init

可以直接一路回车，也可以自己配置相关参数

执行完毕会生成一个 package.json 文件

3.3 将 VuePress 安装为本地依赖

yarn add -D vuepress@next

执行完毕生成的目录结构

├── node_modules
├── package.json
└── yarn.lock

3.4 编辑 package.json 文件

加入内容

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

完整的 package.json 示例

{
  "name": "pressProject",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vuepress": "^2.0.0-beta.67"
  },
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

3.5 启动

yarn docs:dev

运行成功会生成一个 docs 目录

4、使用 hope 主题

提示

该主题需要 vue3 、vuepress2

4.1 添加主题

yarn create vuepress-theme-hope add [dir]

[dir] 目录名称（如果你想用docs这个名字，请务必先把之前生成的docs给删除，我就喜欢用docs）

执行这个命令的时候会有一些选项，按需选择即可；如果你选择困难就按照如下图所示选择：

再运行就可以看到带有主题的效果啦

---

注意

如果你执行上面命令的时候报错了，可能是版本更新了，这里分享一下我遇到的错误

这里的大概意思是 yarn 版本过低

1）升级 yarn 版本

下面的方法修改 yarn 版本作用域是前项目

# 升级到最新版本
yarn set version berry
# 升级到 2
yarn set version 2

提示

这里有一个玄学每次执行升级到2经常会因为网络原因不成功，但是只有执行一次升级到最新版本再删除生成的文件，再执行一次升级到2就会很顺利

执行升级之后会生成一些文件

.yarn
.yarnrc.yml

3）查看版本

yarn -v

2）配置网络代理

编辑.yarnrc.yml文件，加入如下内容：

nodeLinker: node-modules
npmRegistryServer: https://registry.npm.taobao.org/

配置完毕再执行 yarn create vuepress-theme-hope add [dir] 就可以啦！

4.2 文件结构介绍

pressProject/
├── docs            # 上一步生成的目录
│   ├── demo        # demo、posts 是两个示例
│   ├── intro.md    
│   ├── posts
│   ├── README.md   # 主页（我一般会把它改成index.md）
│   └── slides.md
├── node_modules
├── package.json
└── yarn.lock

4.3 主页配置

路径：docs/index.md （原：README.md）

# 设置白天背景图片
bgImage

# 设置夜间背景图片
bgImageDark

# 设置版权
copyrightText

# 配置首页卡片外链（示例）
projects:
  - icon: book
    name: VuePress
    desc: "Vue 驱动的静态网站生成器"
    link: https://vuejs.press/zh/

更多设置

4.4 文章配置

每篇文章顶部的那个 --- 中间的配置项

# 文章标题
title

# icon
icon

# 文章摘要
description

# 时间（格式：yyyy-mm-dd）
date

# 侧边栏设置（取值：false|heading）
sidebar 

# 是否显示在文章中
article

# 页脚设置
footer

# 置顶（取值：数字，越大越靠前）
sticky

# 标签（以下是多标签示例）
tag
 - Vue
 - TypeScript

# 分类（多分类参考多标签）
category 

更多设置

特别说明：
description 这项设置很奇怪，设置了却不生效，翻阅文档发现他说：“如果你想要为文章添加摘要，你可以使用 <!-- more --> 注释来标记它。任何在此注释之前的内容会被视为摘要。”起初看不懂，怎么设置都无效，无意中发现是需要注释和 description 一起使用。

示例：

---
title: 一个示例
description: 示例文章摘要 
footer: ""
---

<!-- more -->

正文正文正文正文正文

4.5 文章加密

在 theme.ts 文件中

encrypt: {
    config: {
      "/demo/encrypt.html": ["1234"],
    },
  },

一目了然，前面是需要加密的文件路径，后面是访问的密码

效果：

4.6 pwa功能

vuepress 是支持 pwa 的，hope 这个主题默认也是开启了 pwa 功能的。

同样是在 theme.ts 文件中，找到 pwa 即可，因为 pwa 必须要 https 并且要发布才能使用，开启之后打开 F12 在 Application 的 Manifest 能看到相关信息，这里也不多做赘述。

5、帮助文档

更多操作请参考下面的文档，要善于使用搜索功能

VuePress 官网：https://v2.vuepress.vuejs.org/zh/

hope 主题官网：https://theme-hope.vuejs.press/zh/guide/

VuePress市场博客-主题：https://marketplace.vuejs.press/zh/themes/blog.html