前端博客2020知识库搭建

作者:云白先生
公众号: 前端微服务
GitHub:github.com/yongbolu

概述

俗话说，好记性不如烂笔头，在信息化的今天，笔头我们已经用的很少了，取而代之的是电脑、手机等一系列终端设备，笔头是什么并没那么重要，但笔头做的事情才是我们关注的重点，做笔记，把我们自己平时的故事和知识点记录下来，方便在以后忘记的时候拿出来看看，做复习用。今天小编将为大家介绍用当下流行的Vuepress搭建一套属于自己的知识库。如果对你有帮助，不要忘记点赞!

第一部分认识VuePress

第1章 VuePress 是什么

VuePress(Vue 驱动的静态网站生成器)是为了支持 Vue及其子项目的文档需求而诞生的。它由两部分组成：

第一部分是一个极简静态网站生成器，它包含由 Vue 驱动的主题系统和插件 API
第二部分是为书写技术文档而优化的默认主题

第2章 VuePress 工作原理

VuePress 网站是一个由 Vue、Vue Router 和 webpack 驱动的单页应用。
在构建时，为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。

第3章 VuePress 特点

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

简洁至上: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
Vue 驱动： 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
高性能: VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。
内置的 Markdown 拓展(为技术文档而优化的内置Markdown拓展)
内置的 Markdown 拓展(在Markdown文件中使用Vue组件)
自动生成Service Worker(支持PWA)
Google Analytics集成
Vue驱动的自定义主题系统
默认主题
多语言支持
响应式布局
支持PWA模式
强大的 Plugin API
基于Git的"最后更新时间

第4章 VuePress 安装环境要求

请确保你的 Node.js 版本 >= 8.6。
安装工具1:yarn(建议)
安装工具2:npm
一定要使用 yarn add vuepress@next或npm install -g vuepress@next 而不是官网的命令,官网的命令是老版本

第5章 VuePress 全局安装

如果你只是想尝试一下 VuePress，你可以全局安装它：

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

# 创建项目目录
mkdir vuepress-demo && cd vuepress-demo

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

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .
复制代码

注意: vuepress dev . 和vuepress build .后面的“.”

第6章 VuePress 项目安装

如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。

# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress@next # 或者：npm install -D vuepress@next

# 新建一个 docs 文件夹
mkdir docs

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

# 开始写作
npx vuepress dev docs
复制代码

注意: 如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。用npm安装执行npx vuepress dev docs会报错，用yarn安装vuepress正常。

默认的主题提供了一个首页（Homepage）的布局 (用于这个网站的主页)。想要使用它，需要在你的根级 README.md(docs/README.md) 的 YAML front matter 指定 home: true。配置如下:

---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---
复制代码

接着，在 package.json 里加一些脚本:

在项目根目录下的 package.json 中添加 scripts ：
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

然后就可以开始写作了:

yarn docs:dev # 或者：npm run docs:dev
就会出现一个和Vuepress一样的网站了
复制代码

要生成静态的 HTML 文件，运行：

yarn docs:build # 或者：npm run docs:build
复制代码

注意: 默认情况下，文件将会被生成在 .vuepress/dist，当然，你也可以通过 .vuepress/config.js 中的 dest 字段来修改，生成的文件可以部署到任意的静态文件服务器上，参考 VuePress部署来了解更多。

第7章 VuePress 目录结构

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
复制代码

目录说明

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

页面访问路由

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

命令行使用

基本用法

vuepress <command> targetDir [options]
复制代码

常用命令

vuepress dev docs
vuepress build docs
vuepress eject
复制代码

第8章 VuePress 主题

这里根据VuePress的默认主题配置,如果默认主题无法满足需求，需要自定义主题如下

1. 替换主题

首先在docs下的 .vuepress 目录下新建 theme文件夹
然后找到该目录 /node_modules/@vuepress/theme-default
把 theme-default 中的所有文件复制到刚才的 theme中,注意不是把 theme-default文件夹复制过去
或者使用指令:vuepress eject将默认主题复制到 .vuepress/theme 目录，以供自定义。
现在,你可以自己修改主题了

2. 加入第三方UI框架

集成ElementUI
进入项目根目录,使用命令 yarn add element-ui -S或者npm i element-ui -S
然后在 .vuepress文件夹下的 enhanceApp.js 进行配置,如果没有 enhanceApp.js 文件则新建这个文件

> enhanceApp.js

import Element from 'element-ui'
export default ({
  Vue, // the version of Vue being used in the VuePress app
  options, // the options for the root Vue instance
  router, // the router instance for the app
  siteData // site metadata
}) => {
 Vue.use(Element, { size: 'small', zIndex: 3000 });
}
复制代码

第9章 VuePress 插件

第10章 VuePress 部署

文档放置在项目的 docs 目录中；
使用的是默认的构建输出位置；
VuePress 以本地依赖的形式被安装到你的项目中
并且配置了如下的 npm scripts:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

第二部分 Nuxt

第11章 Nuxt是什么

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

第三部分 Docsify / Docute

第12章 Docsify / Docute是什么

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

第四部分 Hexo

第13章 Hexo是什么

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

第五部分 GitBook

第14章 GitBook是什么

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

关注我们

点击下方关注我👇👇👇

前端博客

概述

目录

第一部分 认识VuePress