VuePress安装及使用——使用 Markdown 创建你自己的博客网站和电子书

前言

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

例如：官网的 VuePress 快速开始

就是采用 VuePress 生成的，你只需要使用 Markdown 来书写文章内容，其他的 VuePress 帮你搞定。

VuePress 相比于其他以 Markdown 为中心的静态网站生成器，如、GitBook 、docusaurus、 mdBook 、Hexo、Nuxt、VitePress、Docsify 、Docute 更加简单方便，如果你会前端你还可以自己定制主题。

一、依赖环境

• Node.js ，版本需要大于等于 18.16.0
• 包管理器，如 npm 或者 pnpm、yarn 等。

若你还没安装 Node.js，可以参考 Node.js安装与配置 进行下载安装。

二、vuepress 安装和使用

1.初始化

新建一个文件夹，我这里新建的文件夹叫 vuepress ，打开 cmd 窗口进入 vuepress 文件夹所在路径。

然后 cmd 命令行中输入下面的命令，将初始化生成一个 package.json 文件：

npm init -y

2.将 VuePress 安装为本地依赖

npm install -D vuepress@next

3. package.json 中添加脚本

在 package.json 中的 scripts 里添加两行启动脚本

	"docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"

最终的 package.json 长这样：

{
  "name": "vuepress",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
	"docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^2.0.0-rc.0"
  }
}

4. 新建 docs 文件夹

在 vuepress 文件夹下新建 docs 文件夹，用于存放所有的 Markdown 文件。

在 docs 文件夹下新建 README.md 文件，你可以在 README.md 写点内容。

5.启动

执行如下命令启动，启动成功后，会在 docs 下自动生成 .vuepress 文件夹，用于配置。

npm run docs:dev

启动后，你可以浏览器打开http://localhost:8080/ 查看刚才的 README.md 渲染效果 。

6. 效果

三、进阶使用

假如你有很多文章，其中一些是 java 相关的，其中一些是 python 相关的，那怎么让左边的侧边栏分类并只显示文章名称呢？

另外，怎么给最上面的导航栏加上自己的头像、昵称、文章搜索框、和其他导航呢？

1.新增配置文件

在 vuepress/docs/.vuepress/ 下新建 config.js 文件。该配置文件用于配置插件、主题、导航栏、侧边栏等。

在 vuepress/docs/.vuepress/ 下新建 public 文件夹 ，public 文件夹 下 再新建 images 文件夹，把你的头像 logo 图片放里面。

2.安装搜索插件

vuepress 目录下，命令行执行如下命令安装搜索插件：

npm i -D @vuepress/plugin-search@next

3.config.js 中增加配置

下面是我的配置，可参考修改使用。

import { defaultTheme } from 'vuepress'
import { searchPlugin } from '@vuepress/plugin-search'

export default{
  title: '山下海棠',
  description: '山下海棠',
  theme: defaultTheme({
	logo: "/images/head.jpg", //头像logo，默认使用 public 文件夹下的资源，所以路径里不用加 public
	//头部导航栏配置。可使用link方式来自动扫描对应路径下的Markdown文章；也可以使用 children 方式手动向数组中加入文章
	navbar: [  
	  {
        text: 'java',
        link: '/java/',
      },
      {
        text: 'python',
        children: ['/python/JSON.md', '/python/openpyxl.md', '/python/spider.md'],
      }
	 ],
	sidebarDepth: 0, //设置为0，左侧侧边栏文章下不显示标题列表
	sidebar: [       //sidebar控制左边侧边栏
      {
        text: "🧭 java",
		collapsible: true, //可折叠
        children: [
          "/java/socketAndNetty.md",
          "/java/stream.md",
        ],
      },
      {
        text: "☕ python",
		collapsible: true,	//可折叠
        children: [
          "/python/JSON.md",
          "/python/openpyxl.md",
          "/python/spider.md",
        ],
      }]
  }),
  plugins: [
    searchPlugin({
	  locales: {
        '/': {
          placeholder: '搜索文章',
        },
      },
    }),
  ],
}

最终，我的文件目录结构如下：

（如果你的 Markdown 文章里要插入图片，可以在 docs 文件夹下新建 images 文件夹，把图片都放里面，然后在 Markdown 文章里使用相对路径来插入图片）

└─ docs
    └─ .vuepress
    │    ├─ public
    │    │   └─ images
	│    │	     └─ head.jpg
    │    └─ config.js  
    ├─ java 
    │    ├─ socketAndNetty.md
	│    └─ stream.md
    ├─ python
    │    ├─ JSON.md
    │    ├─ openpyxl.md
	│    └─ spider.md
    └─ README.md

4.效果展示

5.注意

在 markdown 语法里：
# 表示一级标题
## 表示二级标题
### 表示三级标题
而 vuepress 在解析渲染的时候会把 markdown 文章里第一个出现的 # 作为文章名，所以建议
文章中第一行使用 # 来作为文章名，使用 ## 作为一级标题 ，使用 ### 作为二级标题。

例如：
就像上面效果展示里，我的 python中JSON使用 这篇文章 markdown 是这样写的:

# python中JSON使用
::: details 目录

[[toc]]

:::

## 一、字典（JSON 对象）与JSON字符串的转换

### 1.字典转JSON字符串

......省略代码块

### 2.JSON字符串转字典

......省略代码块

此外，vuepress 增加了一些对 Markdown 的语法扩展，可参考官网：Markdown 语法扩展

四、使用主题

上面三部分简单的讲解了怎么安装和使用 vuepress ，但页面还不够美观，为此我们可以使用主题。

vuepress 官方提供了一个官方的主题 vuepress-theme-hope

它满足了例如文本对齐、标记、流程图、公式、演示等，同时大大改进了美观度，而且通过主题插件为 VuePress 提供了全方位的增强功能。

如果你想安装其他主题，可在这里寻找社区主题：vuepress 主题

1.安装

在 vuepress 下新建一个文件夹，我这里建了一个叫 themeHope 的文件夹。

使用如下命令安装 vuepress-theme-hope 主题：

npm init vuepress-theme-hope add themeHope

按照提示选择语言和一些基本操作，等待安装完成，启动项目，然后打开 http://localhost:8080/ 可以看到预览效果。

2. 目录结构说明

当安装完 vuepress-theme-hope 主题后，themeHope 文件夹下会生成 README.md 和 .vuepress 文件夹，下面对它们进行简单说明。

（1）README.md

README.md 是博客首页的配置，首页根据此配置文件生成。如果你不需要博客首页可以将其中的配置 home: true 修改为 home: false

首页的更多配置你可以参考官网的：首页配置 和 主页 Frontmatter 配置

（2）.vuepress 文件夹

themeHope/.vuepress/ 文件夹下会生成如下配置文件和文件夹：

• bublic ：该文件夹用来存放图片和静态资源
• config.ts ：整体配置文件
• navbar.ts ：头部导航栏配置文件
• sidebar.ts ：左侧导航栏配置文件
• theme.ts ：主题配置文件

3. 修改配置

(1).删除 themeHope 文件夹下生成的 demo 和 guide 演示示例文件夹。

(2).将项目根目录下 docs 文件夹下的 java 和 python 文件夹复制到 themeHope 文件夹下，然后删除根目录下docs 文件夹。

(3).修改 hemeHope/.vuepress/sidebar.ts 侧边栏配置

import { sidebar } from "vuepress-theme-hope";

export default sidebar({
  "/": [
    "",
	{
      text: "java",				 //显示的类目名称
      icon: "book",				//图标
	  collapsible: true,        //侧边栏可折叠
      prefix: "java/",		   //该类目文章所在的文件夹
      children: "structure",   //自动获取所有文章生成侧边栏
    },
	{
      text: "python",
      icon: "laptop-code",
	  collapsible: true,
      prefix: "python/",
      children: "structure",
    },
  ],
});

(4).修改 hemeHope/README.md 首页配置，home: true 修改为 home: false 关闭首页

4. 启动

执行启动命令

npm run docs:dev

启动后， 浏览器打开 http://localhost:8080 查看效果。

5. 效果

---

参考：
vuepress快速上手
vuepress配置
theme-hope主题
秒建炫酷的开源项目文档，这款工具用起来够优雅！
VuePress-theme-hope2搭建个人网站