VuePress学习指南（上）

VuePress概述

VuePress 是一个静态网站生成器，它基于 Vue.js 和 Markdown 来创建文档网站。VuePress 能够快速创建高质量的文档网站，具有易用性和可定制性。VuePress 采用了现代化的技术栈，包括 webpack、Vue.js、markdown-it 等等，这些技术使得 VuePress 具备自定义主题和插件、支持代码语法高亮、提供搜索和分页等功能。VuePress 还能够对网站进行优化，例如 gzip 压缩、预渲染和缓存等操作，从而提升网站的性能和访问速度。VuePress 的使用非常简单，只需要编写 Markdown 文件即可，同时还可以通过配置文件进行个性化设置。

VuePress和其他静态网站生成器的异同

VuePress 是一种基于 Vue.js 的静态网站生成器，它专注于文档编写和网站构建。与其他静态网站生成器相比，VuePress 有以下异同：

1. 使用 Vue.js：VuePress 使用 Vue.js 框架来构建页面，这使得在开发自定义主题或插件时非常方便，因为大多数 Vue.js 开发人员都会熟悉它。

2. 集成 Markdown：VuePress 支持使用 Markdown 编写文档，并且内置了一个 Markdown 解析器，可以轻松地将 Markdown 文档转换为 HTML 页面。

3. 自定义主题和插件：VuePress 允许用户轻松地创建自定义主题和插件，以满足不同的需求。

4. 独立部署：VuePress 生成的静态文件可以独立部署到任何静态文件托管服务上，例如 GitHub Pages、Netlify 等。

5. 内置搜索：VuePress 内置搜索功能，为用户提供快速查找文档的能力。

6. 静态资源管理：VuePress 可以很好地处理静态资源，例如图片、CSS 和 JavaScript 文件等。

安装VuePress

1. 确认已经安装了Node.js和npm。您可以在终端窗口中输入以下命令来检查它们的版本：

node -v
npm -v

2. 在终端窗口中使用npm全局安装VuePress：

npm install -g vuepress

3. 创建一个新的VuePress项目目录并进入该目录：

mkdir my-docs && cd my-docs

4. 在该目录下创建一个新的VuePress站点：

vuepress create docs

5. 进入docs目录并启动本地服务器：

cd docs
npm run dev

6. 打开浏览器并访问http://localhost:8080/，您应该能够看到一个初始的VuePress页面。

现在您已经成功地安装并运行了VuePress。接下来，您可以根据需要编辑和自定义VuePress主题、页面和文档。

修改默认主题和配置文件

1. 安装VuePress

首先需要安装VuePress。可以使用npm或yarn进行安装。例如，使用npm安装：

npm install -g vuepress

2. 创建VuePress项目

在命令行中使用以下命令创建一个新的VuePress项目：

vuepress create my-site

这将在当前目录下创建一个名为my-site的新目录，并包含VuePress的默认文件和目录结构。

修改默认主题

VuePress提供了默认主题，但也支持自定义主题。在my-site目录中，可以创建一个名为.vuepress的新目录，并在其中创建一个名为theme的新目录。在theme目录中，创建一个名为Layout.vue的文件，用于覆盖默认主题的布局。

接下来，可以从VuePress默认主题的GitHub仓库中下载CSS和其他必要文件，并将它们放置在my-site/.vuepress/theme目录中。然后，将my-site/.vuepress/config.js文件中的theme选项设置为自定义主题目录的路径：

module.exports = {
  theme: './theme/'
}

修改配置文件

配置文件config.js中包含VuePress的所有配置选项。可以根据需要修改这些选项。例如，可以更改网站的标题和描述：

module.exports = {
  title: 'My Site',
  description: 'This is my site'
}

还可以添加自定义页面、插件等。修改完配置文件后，需要重新启动VuePress以使更改生效。

config.js 详解

config.js的详细解析：

1. title: 网站的名称，将会显示在浏览器的标签栏中。

2. description: 网站的描述信息，会在生成的 HTML 页面中添加一个 meta 标签。

3. base: 站点的基础路径，如 /blog/。如果你的站点部署在非根目录下，则需要设置该选项。

4. head: 该选项接收一个数组，里面可以添加一些额外的 标签，如 、 等。

5. themeConfig: 主题配置，包括导航栏、侧边栏、页面滚动等选项。

6. plugins: 插件配置，可以通过此选项引入一些插件来扩展 VuePress 的功能。

7. markdown: Markdown 配置，可以定义 Markdown 渲染时的默认配置，如代码块的语言、是否启用行号等。

8. locales: 多语言支持，可以为你的网站提供多语言翻译功能。

9. extraWatchFiles: 监听文件变化，可以自动刷新页面。

demo：

module.exports = {
  title: 'My VuePress Site', // 网站标题
  description: 'A brief description of my site', // 网站描述
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' }, // 导航栏链接
      { text: 'Guide', link: '/guide/' }, // 导航栏链接
      { text: 'External', link: 'https://google.com' } // 外部链接
    ],
    sidebar: {
      '/': [
        '', // 首页
        'about', // 关于页面
        'contact' // 联系页面
      ],
      '/guide/': [
        '', // 指南首页
        'getting-started', // 入门指南
        'advanced' // 高级使用方法
      ]
    }
  }
}

这个 demo 中，title 和 description 字段分别设置了网站的标题和描述。themeConfig 对象中，nav 属性用于配置网站导航栏，其中包含一个内部链接和一个外部链接。sidebar 属性用于配置侧边栏，其中 / 表示配置网站根目录下的侧边栏，/guide/ 表示配置 /guide 目录下的侧边栏。每个侧边栏都是一个数组，包含了当前目录下的所有 Markdown 文件。

自动发布到github page

通过脚本配置，本地配置直接运行将文档发布到github

package.json里配置

{
  "name": "vuepressdemo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs",
    "test": "echo \"Error: no test specified\" && exit 1",
    "deploy": "bash deploy.sh"
  },
  "keywords": [],
  "author": "fcli",
  "license": "ISC",
  "devDependencies": {
  }
}

添加deploy.sh

#!/usr/bin/env sh 

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.fcli.xyz' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果你想要部署到 https://USERNAME.github.io
git push -f https://github.com/bogart001/bogart001.github.io.git master

# 如果发布到 https://USERNAME.github.io/  REPO=github上的项目
# git push -f [email protected]:USERNAME/.git master:gh-pages

cd -