vuepress使用及踩坑记录小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。 vuepress可以使用md语

小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。

vuepress可以使用md语法快速生成文档博客，此处仅记录个人借助vuepress生成vue组件库文档的过程，以及使用中所遇到的问题（md语法在此不在累赘，自行查看）

初始化和配置

在已有的项目基础上安装依赖（不推荐全局安装）

yarn add -D vuepress # npm install -D vuepress

创建对应目录文件（自行针对项目情况进行调整）

project 
├─── docs 
│  ├── .vuepress 
│     ├── components  // vue组件文件，将会被自动注册为全局组件
│         └── xxx-botton.vue 
│     ├── styles  // 样式文件
│         └── index.styl 
│     ├── public // 静态资源（图片，字体图标等）
│         ├── fonts 
│         └── favicon.ico
│     └── config.js // 配置文件的入口文件
│  ├── views // md页面文件 
│  └── README.md 
└── package.json

在package.json中添加如下命令

{
  "scripts": {
    "dev": "vuepress dev docs", // 本地运行
    "build": "vuepress build docs" // 打包
  }
}

编辑config.js文件，如下所示：（此处留意README.md命名的文件）

module.exports = {
    base:'/', // 部署站点的基础路径，如果你想让你的网站部署到一个子路径下,在‘/’后面追加对应路径（若设置不正确，部署以后的项目，css和js路径会错误）
    title: 'xxx', // 网站的标题，它将会被用作所有页面标题的前缀，默认下，它也会显示在导航栏上
    description: '基于vue2.X的组件库', // 网站的描述，它将会以 `<meta>` 标签渲染到当前页面的 HTML 中
    head: [ // 额外的需要被注入到当前页面的 HTML `<head>` 中的标签
      ['link', { rel: 'icon', href: '/favicon.ico' }]
    ],
    themeConfig: {
      nav: [ // 顶部导航
        { text: 'Home', link: '/' },
        { text: 'Gitee', link: 'https://gitee.com' },
      ],
      sidebar: [ // 菜单
          {
              title: '组件', // 菜单title
              collapsable: false, // 菜单是否折叠
              children: [ // 对应子菜单
                {
                    title: '基础',
                    collapsable: false,
                    children:[
                      {
                        title: 'Button',
                        collapsable: false,
                        // 踩坑提示：如果是README.md文件只需要写'views/components/basic/',否则不加载
                        path: 'views/components/basic/Button.md', 
                      },
                      {
                        title: 'Icon',
                        collapsable: false,
                        path: 'views/components/basic/Icon.md',
                      },
                  ]
                },
            }
         ]
      },
      scss:{ //配置 scss 根目录
         includePaths: [path.join(__dirname, './style')]
     }
 }

更多详细配置请查看vuepress官网

首页配置（docs/README.MD文件）

home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: title1
  details: 这里是详细内容
- title: title2
  details: 这里是详细内容
- title: title3
  details: 这里是详细内容
footer: 这里是首页底部的文本内容

在md文件中使用vue，在标签中使用定义在components中的文件，在.vuepress/components中的vue文件将会被自动注册为全局组件，因此可以直接使用对应命名的组件，无需再次引入。

// Button.MD
<ClientOnly>
  <xxx-button/>
</ClientOnly>

在vuepress中使用阿里巴巴矢量图

将阿里巴巴矢量图静态文件放到.vuepress/public/fonts文件夹中（不然打包以后会丢失对应字体文件），在使用vue的时候通常会在main.js中引入public中的的css文件（引入其他路径下的打包后也会丢失），此时在config中通过require或者在vue文件中的style中通过@import（）引入对应css文件。 #####- 运行和打包使用在package.json中配置的npm run docs:dev进行本地运行，npm run docs:build进行打包，打包后的文件在.vuepress/dist下

vuepress使用及踩坑记录