vuepress入门笔记背景介绍每一个公司都拥有组件库或者各种各样的前端工具，对于这些工具的使用，拥有一篇高质量的技术

背景介绍

每一个公司都拥有组件库或者各种各样的前端工具，对于这些工具的使用，拥有一篇高质量的技术文档是一个非常不错的选择。像饿了么ui组件库，vue文档等那样，清晰简明大方，可以让团队的人节省更多的一个学习成本。由此，尤大大发明了一个神奇的宝贝-----vuepress

我们都知道，程序员写文档很注重md语法，越来越多的工具也给予md语法来创造更多实用的工具。就掘金而言，掘金的文档编写也是通过md语法来编写。本文不介绍md语法的内容，md语法可以通过这个链接学习markdown。

vuepress介绍

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

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

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

vuepress是基于md语法来编写文档，但你也可以在md文件使用vue的写法，比如加入html标签包裹，注意留有空行才能显示，加入script标签写js逻辑，加入style标签写css样式

创建vuepress

全局安装VuePress

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

新建文件夹

可以手动右键新建，也可以使用下面的命令新建文件夹：

mkdir project

项目初始化

进入到project文件夹中，使用命令行初始化项目:

yarn init -y 
# 或者 npm init -y

将会创建一个package.json文件，长这样子：

{
  "name": "project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

在project的根目录下新建docs文件夹：

这个文档将作为项目文档的根目录来使用：

mkdir docs

在docs文件夹下创建`.vuepress`文件夹：

mkdir .vuepress

所有 VuePress 相关的文件都将会被放在这里

在`.vuepress`文件夹下面创建`config.js`:

touch config.js

config.js是VuePress必要的配置文件，它导出一个javascript对象。

你可以先加入如下配置：

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

在`.vuepress`文件夹下面创建public文件夹:

mkdir public

这个文件夹是用来放置静态资源的，打包出来之后会放在.vuepress/dist/的根目录。

首页(像VuePress文档主页一样)

在docs文件夹下面创建一个README.md：

默认的主题提供了一个首页，像下面一样设置home:true即可，可以把下面的设置放入README.md中，待会儿你将会看到跟VuePress一样的主页。

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

ps：你需要放一张图片到public文件夹中。

我们的项目结构已经搭好了：

project
├─── docs
│   ├── README.md
│   └── .vuepress
│       ├── public
│       └── config.js
└── package.json

在 `package.json` 里添加两个启动命令:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

启动你的VuePress：

默认是localhost:8080端口。

yarn docs:dev
# 或者：npm run docs:dev

构建：

build生成静态的HTML文件,默认会在 .vuepress/dist 文件夹下

yarn docs:build 
# 或者：npm run docs:build

基本配置：

最标准的当然是官方文档,可以自己的需求来配置config.js。

可以参考一下下面的配置：

module.exports = {
  title: '网站标题',
  description: '网站描述',
  // 注入到当前页面的 HTML <head> 中的标签
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }], // 增加一个自定义d的favicon(网页标签的图标)
  ],
  base: '/web_accumulate/', // 这是部署到github相关的配置 下面会讲
  markdown: {
    lineNumbers: true // 代码块显示行号
  },
  themeConfig: {
    sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题，显示在侧边栏上。
    lastUpdated: 'Last Updated' // 文档更新时间：每个文件git最后提交的时间
  }
};

导航栏配置：

module.exports = {
  themeConfig: {
    nav:[
      { text: '前端算法', link: '/algorithm/' }, // 内部链接 以docs为根目录
      { text: '博客', link: 'http://obkoro1.com/' }, // 外部链接
      // 下拉列表
      {
        text: 'GitHub',
        items: [
          { text: 'GitHub地址', link: 'https://github.com/OBKoro1' },
          {
            text: '算法仓库',
            link: 'https://github.com/OBKoro1/Brush_algorithm'
          }
        ]
      }        
    ]
  }
}

侧边栏配置：

module.exports = {
  themeConfig: {
      sidebar:{
        // docs文件夹下面的accumulate文件夹 文档中md文件 书写的位置(命名随意)
        '/accumulate/': [
            '/accumulate/', // accumulate文件夹的README.md 不是下拉框形式
            {
              title: '侧边栏下拉框的标题1',
              children: [
                '/accumulate/JS/test', // 以docs为根目录来查找文件 
                // 上面地址查找的是：docs>accumulate>JS>test.md 文件
                // 自动加.md 每个子选项的标题 是该md文件中的第一个h1/h2/h3标题
              ]
            }
          ],
          // docs文件夹下面的algorithm文件夹 这是第二组侧边栏 跟第一组侧边栏没关系
          '/algorithm/': [
            '/algorithm/', 
            {
              title: '第二组侧边栏下拉框的标题1',
              children: [
                '/algorithm/simple/test' 
              ]
            }
          ]
      }
  }
}

当然你也可以从github上搜索并下载某个大神的配置，这里制作简单基础的配置介绍

安装最新版的vuepress是基于vue3的基础框架，当然你可以使用vue2的语法也可以使用vue3的语法

FAQ

在自己编写文档时需要使用到其他vue插件，使用低版本的vuepress创建enhanchApp.js文件来配置导入全局应用配置，没有效果？最新版的vuepress中导入其他第三方插件的方式与vuepress低版本有所不同，可以通过配置config文件中的一个api-----clientAppEnhanceFiles来配置，在config配置文件同级下创建clientAppEnhance.ts文件，在这个文件里面可以配置一些全局应用配置，比如设置vue全局属性或者引入vue插件等

//// clientAppEnhance.ts

import { defineClientAppEnhance } from '@vuepress/client';

export default defineClientAppEnhance(({ app, router, siteData }) => {
    // VueClipboard.config.autoSetContainer = true
})

///// config.js

import { resolve } from 'path'

module.exports = {
  clientAppEnhanceFiles: path.resolve(__dirname, './clientAppEnhance.ts')
}

vuepress入门笔记