Vuepress记录文档

Posted 2021-09-29 。。

在已有项目中安装

  // 安装：
  npm install -D vuepress
  // 创建一个docs 目录
  mkdir docs
  // 创建一个 markdown 文件(相当于入口页)
  echo \'# Hello VuePress\' > docs/README.md
  // package.json添语句
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }

运行

npm run docs:dev

打包

npm run docs:build

运行后出现乱码问题：

解决方式：修改md文件编码为UTF-8, 即可正常显示

如何使用：

目录结构

.
├── 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: 客户端应用的增强。

首页docs/README.md

该页为项目的首页，支持配置：

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

配置config.js

结构：

  module.exports = {
    title: \'组件库文档\',
    description: \'组件库使用方法说明\',
  }

官方文档地址配置参考

这里介绍部分常用属性：

1. title标题：

   配置当前文档标题（显示在文档左上角和首页位置）

2. description描述：

   配置当前文档描述部分（显示在文档首页标题之下）

3. base网站将在其部署的基本 URL。(Default: \'/\')

   当你的文档默认需要部署在根目录时无需配置，当需要放在doc子路径下时，请配置base: \'/doc/\', 请注意：这里前后都需要/

4. port端口号: (Default: 8080)

   运行时的端口号

5. theme自定义主题：(Default: undefined)

   指定此选项来使用自定义主题。

6. themeConfig: (Default: {})

   为使用的主题提供配置选项。这些选项将根据你使用的主题而有所不同。具体使用参见默认主题配置(default theme config)

7. plugins: 插件扩展

   • 直接引入js：

       module.exports = {
         plugins: [
           require(\'./my-plugin.js\')
         ]
       }

   • 使用npm上的插件：

       module.exports = {
         plugins: [ \'vuepress-plugin-xx\' ]
       }

     更多属性请参照官方文档

palette.styl样式变量修改项：

// 颜色
$accentColor = #283eb2
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961

// 布局
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px

// 响应式变化点
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px

enhanceApp.js应用增强

类似vue中的mian.js的作用，用于增强应用的功能，如element-ui将在此处进行注册引入。

结构：

import Element from \'element-ui\';
import \'element-ui/lib/theme-chalk/index.css\';
 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
 }) => {
   // ...apply enhancements to the app
   Vue.use(Element);
 }

注意：引入某些库时会出现运行时没任何问题，而打包时报window is not defined或者document is not defined导致打包时失败的话，这是由于vuepress采用的是服务端渲染 所以此时找不到对应的window，请修改为

 import ElementUI from \'element-ui\';
 import XXX from "XXX";
 
 
 export default ({
   Vue, // VuePress 正在使用的 Vue 构造函数
 }) => {
   // ...做一些其他的应用级别的优化
   Vue.use(ElementUI);
   Vue.mixin({
     mounted(){
       Vue.component(XXX.name, XXX);
     }
   })
 };

或者改为

 // 扩展写这里
 import Element from \'element-ui\';
 import \'element-ui/lib/theme-chalk/index.css\';
 export default async ({
   Vue,
   options,
   router,
   isServer
 }) => {
   const components = await import(\'XXX\')
   Vue.use(Element);
   Vue.use(components.default)
 };