如何使用Vue和VuePress构建文档系统

介绍

文档是成功项目的关键部分。但是，您的项目可能不需要完整的文档系统。在这些情况下，静态页面可能就足够了。

VuePress 将文件夹中结构化的 Markdown 文件解析为 HTML 文件以提供服务。 VuePress 附带 Vue、Vue Router 和 webpack。每个 Markdown 文件都被解析为一个 Vue 模板，并且资产由 webpack 捆绑。将 Markdown 文件解析为 Vue 模板还允许您以单文件组件的形式使用原生 Vue 脚本。

注意： 本教程在编写时考虑了手动安装。还提供了一个名为 create-vuepress-site 的自动脚手架工具。

在本文中，您将构建一个静态文档网站，它也是一个使用 Vue 支持的静态站点构建器 VuePress 的单页应用程序。

先决条件

如果您想继续阅读本文，您将需要：

Node.js 的本地开发环境。关注【X7X】如何安装Node.js并创建本地开发环境【X76X】。

本教程已使用 Node v16.6.2、npm v8.1.0 和 vuepress v1.8.2 进行了验证。

第 1 步 — 设置项目

在本节中，您将创建项目并安装 VuePress。

首先，新建一个项目目录：

mkdir vuepress-example

接下来，切换到新的项目目录：

cd vuepress-example

然后，初始化一个新项目：

npm init --yes

此命令快速搭建一个新项目并创建一个 package.json 文件。

接下来，在本地安装 VuePress 作为开发依赖项：

npm install vuepress@1.8.2 --save-dev

在项目中安装 VuePress 后，您将拥有所需的一切，因为 VuePress 附带了用于该项目的默认文档主题。

此时，您应该修改 package.json 的脚本来构建和服务于 VuePress 站点。

在代码编辑器中打开 package.json 并添加突出显示的代码行：

包.json

{
  "name": "vuepress-example",
  "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": "^1.8.2"
  }
}

至此，您已经安装了 VuePress 并修改了 package.json 以支持 dev 和 build 命令。

第 2 步 — 创建主页

在本节中，您将使用占位符文本创建目录结构和 Markdown 文件。

在 VuePress 中创建文件夹时要小心，因为它会根据文件夹和 Markdown 文件的目录结构对其进行评估。文件夹中的每个 Markdown 文件都会编译成一个 HTML 文档，其路由是父文件夹。

首先，创建一个 docs 目录来存放组件和配置：

mkdir docs

现在，使用您的代码编辑器在此目录中创建一个新的 index.md 文件：

文档/index.md

---
home: true
actionText: Counter Component
actionLink: /counter/
features:
- title: Embedded Vue Compments
  details: A Vue counter developed using Vue is embedded in this documentation. Now that's the power of VuePress!
- title: Documentation made with VuePress
  details: This entire documentation was made with VuePress which parsed Markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---

Markdown 文件中特殊的 “front matter”语法（YAML、JSON 或 TOML 格式）指示 VuePress 提供 title、lang 和其他属性。

此时，您可以构建和服务应用程序并观察您目前拥有的内容：

npm run docs:dev

构建应用程序后，您将看到一条成功消息，该消息还提供了要访问的 URL（默认情况下应为 localhost:8080）。

现在，在您的网络浏览器中打开此 URL。 Markdown 代码将为 Counter Component 生成一个按钮、有关功能的信息列和页脚。

VuePress 附带了一个热重载功能，可以实现在开发过程中对应用程序所做的任何更改。

但是，如果在本地开发服务器处于活动状态时创建 Vue 组件，则需要重新启动开发服务器。

第 3 步 - 创建计数器页面

出于本项目的目的，您的文档将跟踪增加和减少数值的 Counter 组件的详细信息。

在docs目录下，新建.vuepress子目录：

mkdir docs/.vuepress

并在这个.vuepress目录下，新建一个components子目录；

mkdir docs/.vuepress/components

现在，使用您的代码编辑器在 .vuepress/components 目录中创建一个新的 counter.vue 文件：

docs/.vuepress/components/counter.vue

<template>
  <div class="counter">
    <h1>{{ number }}</h1>
    <button @click="increment">Increment</button>
    <button @click="decrement">Decrement</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      number: 0
    };
  },
  methods: {
    increment() {
      if (this.number >= 0) {
        this.number++;
      }
    },
    decrement() {
      if (this.number > 0) {
        this.number--;
      }
    }
  }
};
</script>

<style scoped>
.counter {
  display: inline-block;
  margin-left: 30%;
}

button {
  display: inline-block;
  padding: 20px;
  margin: 10px;
  font-weight: bold;
  border-radius: 5px;
  box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
}

h1 {
  text-align: center;
}
</style>

此代码将显示值 (number)，并且根据与 Increment 或 Decrement 按钮交互的次数，该值会发生变化。

现在，您将创建页面以显示 <counter/> 组件。

在docs目录下，新建counter子目录：

mkdir counter

现在，使用您的代码编辑器在 docs/counter 目录中创建一个新的 README.md 文件：

docs/counter/README.md

---
title: Counter Component
---
# Counter Component

<counter/>

## Details

The `counter` component allows users to **Increment** and **Decrement** numeric values. The value starts at `0` and has a minimum value of `0`.

### Props

n/a

### State

n/a

在此目录中创建几个附加页面。该演示将包括 usage.md：

docs/counter/usage.md

---
title: Counter Component - Usage
---
# Usage

Currently, this component is used in our app as part of a demonstration.

和 see-also.md：

docs/counter/see-also.md

---
title: Counter Component - See Also
---
# See Also

* [Number](https://en.wikipedia.org/wiki/Number)
* [Increment and decrement operators](https://en.wikipedia.org/wiki/Increment_and_decrement_operators)

这些文件稍后将转换为静态页面。

现在您拥有所有必需的 Markdown 文件。

第 4 步 - 配置布局和样式

在本节中，您将配置站点以使用指定的 title、description、nav 和 sidebar。

config.js 文件用于自定义文档系统。使用您的代码编辑器在 .vuepress 目录中创建一个新的 counter.vue 文件：

docs/.vuepress/config.js

module.exports = {
  title: 'VuePress',
  description: 'A demo documentation using VuePress',
  themeConfig: {
    nav: [
      { text: 'Counter', link: '/counter/' }
    ],
    sidebar: [
      {
        title: 'Counter',
        collapsable: false,
        children: [
          ['/counter/usage', 'Usage'],
          ['/counter/see-also', 'See Also']
        ]
      }
    ]
  }
};

首先，您指定网站的 title 并为其分配一个 description，这有利于 SEO。这个 title 和 description 自动在网站上提供一个带有搜索栏的索引搜索系统。

脚本中的下一个是 themeConfig 对象，它接收在主题上实现某些功能所需的参数。要创建 navbar，您需要创建一个 nav 数组，其中包含指定每个 nav 元素的显示文本和路径的对象。

注意：您可以在官方文档中了解更多关于导航栏的信息。

此代码还具有分组的 sidebar 功能，因此用户可以随时快速浏览文档中的菜单。可以使用侧栏组上的 collapsable 属性将 sidebar 菜单设置为默认折叠。

注意：你可以在官方文档中了解更多关于侧边栏的信息。

作为配置演示的最后一步，您将使用样式覆盖默认颜色。

在docs/.vuepress/目录结构下，新建styles子目录：

mkdir docs/.vuepress/styles

现在，使用您的代码编辑器在 .vuepress/styles 目录中创建一个新的 palette.styl 文件：

docs/.vuepress/styles/palette.styl

$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

此语法和文件扩展名适用于 Stylus sheet。 VuePress 使用 Stylus 来配置颜色和断点。

使用以下命令保存更改并重新启动开发服务器：

npm run docs:dev

请注意，对 .styl 文件所做的更改会立即反映在浏览器中。

您现在已经完成了带有各个页面的文档系统。

结论

在本教程中，您使用 VuePress 开发了一个静态文档网站，它也是一个单页应用程序。

VuePress 提供了在引入交互式演示的 Markdown 文件中编写 Vue 脚本的灵活性。静态站点因其速度、安全性和可维护性而被认为是有用的。

VuePress 对 SEO 友好，默认情况下提供了一种在您的页面上使用 Google Analytics 实现分析跟踪的方法。此外，VuePress 附带了一个最小的搜索系统，可以索引网站上的所有标题并在搜索时显示它们。尽管 VuePress 为文档提供了默认的响应式布局，但它也支持用于样式的自定义布局。

通过修改项目以包含其他文件夹和相应的 Markdown 文件来继续学习。

如果您想了解有关 VuePress 可用选项的更多信息，请参阅我们对 VuePress 的介绍。