vuePress学习 - 技术栈

vuePress官网
Vue 驱动的静态网站生成器

简洁至上

以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。

Vue 驱动

享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。

高性能
VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。

bash 复制代码

# 安装
yarn global add vuepress # 或者：npm install -g vuepress

# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

注意

请确保你的 Node.js 版本 >= 8.6。

介绍

VuePress 由两部分组成：第一部分是一个极简静态网站生成器 (opens new window)，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。

它是如何工作的？

事实上，一个 VuePress 网站是一个由 Vue (opens new window)、Vue Router (opens new window)和 webpack (opens new window)驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。

在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt (opens new window)的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby (opens new window)。

为什么不是下面这些?

Nuxt
VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。

Docsify / Docute

这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！

Hexo
Hexo 一直驱动着 Vue 的文档 ------ 事实上，在把我们的主站从 Hexo 迁移到 VuePress 之前，我们可能还有很长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。

GitBook

我们的子项目文档一直都在使用 GitBook。GitBook 最大的问题在于当文件很多时，每次编辑后的重新加载时间长得令人无法忍受。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。GitBook 背后的团队如今也更专注于将其打造为一个商业产品而不是开源工具。

快速上手

js 复制代码

npm init // 生成了package.json文件
npm install -D vuepress
mkdir docs && echo '# Hello VuePress' > docs/README.md
// package.json内加下面代码
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
npm run docs:dev // 启动服务

VuePress 会在 http://localhost:8080 (opens new window)启动一个热重载的开发服务器。

现在，应该已经有了一个简单可用的 VuePress 文档。接下来，了解一下推荐的目录结构和 VuePress 中的基本配置。

等了解完上文介绍的基础概念，再去学习一下如何使用静态资源，Markdown 拓展和在 Markdown 中使用 Vue 来丰富你的文档内容。

当文档逐渐成型的时候，不要忘记 VuePress 的多语言支持并了解一下如何将你的文档部署到任意静态文件服务器上。

目录结构

├── docs
│   ├── .vuepress (用于存放全局的配置、组件、静态资源等。)
│   │   ├── components (该目录中的 Vue 组件将会被自动注册为全局组件)
│   │   ├── theme (用于存放本地主题)
│   │   │   └── Layout.vue
│   │   ├── public (静态资源目录)
│   │   ├── styles (用于存放样式相关的文件)
│   │   │   ├── index.styl（将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级）
│   │   │   └── palette.styl（用于重写默认颜色常量，或者设置新的 stylus 颜色常量）
│   │   ├── templates (存储 HTML 模板文件)
│   │   │   ├── dev.html（用于开发环境的 HTML 模板文件）
│   │   │   └── ssr.html（构建时基于 Vue SSR 的 HTML 模板文件）
│   │   ├── config.js (配置文件的入口文件，也可以是 YML 或 toml)
│   │   └── enhanceApp.js (客户端应用的增强)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

对于上述的目录结构，默认页面路由地址如下：

文件的相对路径	页面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

基本配置

一个 VuePress 网站必要的配置文件是 .vuepress/config.js，它应该导出一个 JavaScript 对象：

js 复制代码

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}

对于上述的配置，如果你运行起 dev server，你应该能看到一个页面，它包含一个页头，里面包含一个标题和一个搜索框。VuePress 内置了基于 headers 的搜索 ------ 它会自动为所有页面的标题、h2 和 h3 构建起一个简单的搜索索引。更多配置看这里

主题配置

一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中，目前自带了一个默认的主题（正是你现在所看到的），它是为技术文档而设计的。同时，默认主题提供了一些选项，让你可以去自定义导航栏（navbar）、侧边栏（sidebar）和首页（homepage）等，详情请参见默认主题。

如果你想开发一个自定义主题，可以参考自定义主题。

应用级别的配置

由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置，当该文件存在的时候，会被导入到应用内部。enhanceApp.js 应该 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等：

js 复制代码

// 使用异步函数也是可以的
export default ({
  Vue, // VuePress 正在使用的 Vue 构造函数
  options, // 附加到根实例的一些选项
  router, // 当前应用的路由实例
  siteData, // 站点元数据
  isServer // 当前应用配置是处于 服务端渲染 或 客户端
}) => {
  // ...做一些其他的应用级别的优化
}

插件 API 中的 enhanceApp

TypeScript 配置

VuePress 支持配置文件的类型提示和类型检查，以及默认主题或自定义主题的类型提示。
照片

快速开始

创建 .vuepress/config.ts，内容如下:

bash 复制代码

import { defineConfig } from "vuepress/config";
export default defineConfig({
  // ...
});

主题的类型推断

默认情况下，defineConfig 帮助程序使用默认主题的配置类型：

js 复制代码

import { defineConfig } from "vuepress/config";

export default defineConfig({
  /**
   * Type is `DefaultThemeConfig`
   */
  themeConfig: {
    repo: "vuejs/vuepress",
    editLinks: true,
    docsDir: "packages/docs/docs"
  }
});

如果你使用自定义主题，可以使用 defineConfig4CustomTheme帮助器，为你的主题传递通用类型：

js 复制代码

import { defineConfig4CustomTheme } from "vuepress/config";

interface MyThemeConfig {
  hello: string;
}

export default defineConfig4CustomTheme<MyThemeConfig>({
  /**
   * Type is `MyThemeConfig`
   */
  themeConfig: {
    hello: "vuepress"
  }
});

第三方插件

值得注意的是，如果你使用元组样式配置，第三方插件可能不支持插件速记。这是因为从类型系统的角度来看，未知的快捷方式相当于 string，导致类型推断失败。

默认情况下，只有官方维护和 VuePress 社区 (opens new window)下的插件支持快捷方式，请随时提交拉取请求，以在此文件 (opens new window)中添加您的插件。