• 如果您觉得本站非常有看点,那么赶紧使用Ctrl+D 收藏吧

Vuepress记录文档

互联网 diligentman 3天前 5次浏览

在已有项目中安装

  // 安装:
  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)
 };

程序员灯塔
转载请注明原文链接:Vuepress记录文档
喜欢 (0)