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

目录

• 前言
• 一、依赖环境
• 二、vuepress 安装和使用
• • 1.初始化
  • 2.将 VuePress 安装为本地依赖
  • 3. package.json 中添加脚本
  • 4. 新建 docs 文件夹
  • 5.启动
  • 6. 效果
• 三、进阶使用
• • 1.新增配置文件
  • 2.安装搜索插件
  • 3.config.js 中增加配置
  • 4.效果展示
  • 5.注意
• 四、使用主题
• • 1.安装
  • 2. 目录结构说明
  • • （1）README.md
    • （2）.vuepress 文件夹
  • 3. 修改配置
  • 4. 启动
  • 5. 效果

前言

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搭建个人网站