VuePress静态文档构建说明

1,185 阅读10分钟

VuePress从零搭建

这篇文章主要是记录自己在使用VuePress过程中所遇到的问题以及如何一步一步的解决问题。

安装vuepress前,请确保你的 Node.js 版本 >= 8

全局安装

# 安装
yarn global add vuepress 或者:npm install -g vuepress

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

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

注意 :vuepress dev .和vuepress build .后面的.。

在现有项目中安装

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

# 新建一个 docs 文件夹
mkdir docs

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

# 开始写作
npx vuepress dev docs

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

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

开始写作

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

第一个坑:我的项目就是依赖webpack 3.6.0同时也是用npm安装依赖,然后继续使用npm安装vuepress,然后执行npx vuepress dev docs的时候报错了,上网查了好久也没有解决问题,最后使用yarn安装vuepress成功了。

如果你的现有项目依赖了 webpack 3.x,推荐使用 yarn而不是 npm 来安装 vuepress。

要生成静态的 HTML 文件,运行:

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

默认情况下,文件将会被生成在 .vuepress/dist,也可以通过 .vuepress/config.js 中的 dest 字段来修改.

以上步骤都成功以后,就可以在浏览器总看到页面了,接下来就是对页面进行布局

主题配置

本文是根据VuePress默认主题配置

1.首页

在docs文件夹下创建.vuepress文件夹README.md文件。(如果以及有了就不要再新建)
根目录下的README.md文件可以当作首页,在文件中加入下面文字:

---
home: true
actionText: 快速上手 
actionLink: /guide/install/install
---

可以根据自己的需要添加、删除、修改,这就完成了首页的布局
actionLink: /guide/install/install就是首页后要显示的下一个页面

接下来在docs文件夹中创建guide文件夹(根据自己的需要命名)。这个文件夹中放的是markdown文件,每一个markdown文件对应一个页面。至于页面之间的跳转和页面导航栏和侧边栏布局在config.js文件中设置。
VuePress 网站必要的配置文件是 .vuepress/config.js,它应该导出一个 JavaScript 对象:

module.exports = {
      title: 'VuePress',
    description: 'VuePress',
}

对于上述的配置,运行yarn docs:dev,你应该能看到一个页面,它包含一个页头,里面包含一个标题和一个搜索框。

2.导航栏

可以通过 themeConfig.nav 增加一些导航栏链接:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [       
           {text: '指南',link:'/guide/install/install'}
        ]
  }
}

当你提供了一个 items 数组而不是一个单一的 link 时,它将显示为一个 下拉列表

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese/' },
          { text: 'Japanese', link: '/language/japanese/' }
        ]
      }
    ]
  }
}

3.侧边栏

想要使侧边栏(Sidebar)生效,需要配置 themeConfig.sidebar

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
        {
            title: '开发指南',
            collapsable: false, //是否展开
        },
          ['./guide/install/install','安装'],
           ['./guide/started/started','快速上手'],
        {
            title: '组件',
            collapsable: false
        },
        ['./guide/icon/icon','icon'],
    ]
  }
}

可以省略 .md 拓展名,同时以 / 结尾的路径将会被视为 */README.md
如果想要显示地指定链接的文字,使用一个格式为 [link, text] 的数组。
具体配置可以根据官网配置:默认主题配置

这是浏览器显示效果:


现在页面基本也搭建完成,可以在页面之间进行切换。下一步是如何在markdown中使用vue组件,也就是在页面中展示自己的项目。

在markdown中使用Vue

.vuepress中创建components文件夹。
所有在 .vuepress/components 中找到的 *.vue 文件将会自动地被注册为全局的异步组件。

如果需要引入静态文件,可以在.vuepress下新建public文件夹,里面可以放静态文件。

因为本文的案例是展示Icon图标,所有引入了svg.jssvg.js可以在www.iconfont.cn/中获取,本文使用## symbol引用具体方法请访问官网。放在public文件夹中,可以在components文件夹中的组件引入。

这是docs文件夹目录结构


.
└─ .vuepress
   └─ components
      ├─ demo-1.vue
      └─ Icon
         └─ vi-icon.vue

可以直接使用这些组件在任意的 Markdown 文件中(组件名是通过文件名取到的):

<demo-1/>
<Icon-vi-icon/> //文件名和组件名之间同`-`连接

完成这一步以后就可以在页面中看到自己的组件在页面中展示了,但是在运行下面命令进行打包的时候会报错:
报错原因参考官网文档:浏览器的 API 访问限制

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

解决这个问题只需要在使用Vue组件的markdown文件中使用<ClientOnly></ClientOnly>将组件包裹起来。如:

<ClientOnly>
  <Icon-vi-icon/>
</ClientOnly>

注意:在markdown文件中如果需要给组件名缩进,不要用tab键,会被当做markdown语法解析。

浏览器效果图


到这一步,基本上可以在页面中展示自己的组件。下一篇将继续写如何通过Vue组件实现跟:Element相似的效果。

(二) 

因为可以在markdown中使用Vue组件,所以可以自己专门写一个Vue组件来写一个效果跟:Element相似的页面。

在进行下一步之前先运行两名两个命令:
yarn add vue-highlight.js
yarn add highlight.js

想要在组件中使用这两个包,所以需要做一些配置,在docs\.vuepress下添加enhanceApp.js文件,将下面代码加进去

import  VueHighlightJS  from  'vue-highlight.js';
import  'highlight.js/styles/dark.css';
export  default ({
    Vue, 
}) => {
    Vue.use(VueHighlightJS)
}

接下来就是写Vue组件,用来实现自己项目组件和代码的展示效果,也就是项目文档的布局和样式。
由于代码比较多,这里就不放代码了,可以从这里下载这次案例的所有代码GitHub

效果图



到了这一步,大部分功能基本上都实现了。

自定义样式

docs\.vuepress下添加override.styl,通过编辑override.styl文件可以更改VuePress默认样式。
如果需要对页面的样式进行修改,只需要在override.styl在这个.theme-container.custom-page-class{}里面对页面中对应的类进行修改就可以修改页面默认样式。例子如下:

.theme-container.custom-page-class {
    /* 特定页面的 CSS */
    /*.sidebar在页面中是侧边栏的类名,通过这个可以修改侧边栏的样式和布局*/
    .sidebar{
        width: 16rem;
    }
    @media(max-width:  959px){
        .sidebar{
            width: 15rem;
        }
    }
}

写好这个以后,在需要修改默认样式的页面中将这个文件引入使用,使用方法如下:
在对应的页面的markdown文件中添加pageClass: custom-page-classcustom-page-class这个得跟override.styl文件中.theme-container.custom-page-class的一样。
icon.md文件的开头添加:

---
pageClass: custom-page-class
---

这样就可以修改icon这个页面的默认样式

需要注意的是在markdown使用组件,需要用<ClientOnly></ClientOnly>将组件包裹起来,否则会报错。如:

<ClientOnly>
  <Icon-vi-icon/>
</ClientOnly>

本次案例代码:GitHub


VuePress实现代码高亮及代码折叠

最近在vuepress中撰写UI框架文档时发现在组件中插入演示代码没高亮,虽然在文档markdown中写代码有高亮但就无法实现折叠了,而且vuepress没有提供折叠代码的配置,因此实现一个折叠组件外加代码高亮的插件就十分有必要。

一、编写代码折叠mixin.js

/docs/.vuepress下创建mixin.js文件,编写代码折叠逻辑。

export default {
  data () {
    return {
      //每一个区域的高度
      codeParent: [],
      codeHeightArr: [],
      //每个区域的显示状态
      isShow: [],
    }
  },
  methods: {
    //根据子元素的高度 设置代码区域父元素的高度
    showCode (index) {
      this.$set(this.isShow, index, !this.isShow[index])
      this.$nextTick(() => {
        if (this.isShow[index] === true) {
          this.codeParent[index].style.height = +this.codeHeightArr[index] + 25 + 'px'
        } else {
          this.codeParent[index].style.height = 0
        }
      })
    },
    //得到所有代码区域的高度
    getCodesHeight () {
      const arr = document.getElementsByClassName('code-content-height')
      this.codeParent = document.getElementsByClassName('code-content')
      const arrLength = arr.length
      for (let i = 0; i < arrLength; i++) {
        this.codeHeightArr.push(arr[i].getBoundingClientRect().height)
        this.isShow.push(false)
      }
    },
  },
  mounted () {
    //异步获取当前组件内部 code区域的高度 以便于给点击的时候使用
    this.$nextTick(() => {
      this.getCodesHeight()
    })
  },
}

同目录下创建enhanceApp.js这里引入折叠代码的相关css应用于全局

import './public/index.scss'
export default ({
                  Vue, // VuePress 正在使用的 Vue 构造函数
                  // options, // 附加到根实例的一些选项
                  // router, // 当前应用的路由实例
                  // siteData // 站点元数据
                }) => {
// ...做一些其他的应用级别的优化
}

/doc/.vuepress/public创建index.scss

.theme-container.sidebar-open .sidebar {
  box-shadow: 0 0 10px rgba(0, 0, 0, 0.2);
  border: 0;
}
.sidebar, .navbar {
  z-index: 10000;
}

.component-wrapper {
  border: 1px solid #ebebeb;
  border-radius: 3px;
  transition: .2s;

  .component-wrapper-demo {
    padding: 24px 24px 15px 24px;
  }

  h4 {
    margin: 55px 0 20px;
  }

  &:hover {
    .lock-code .lock-code-word {
      font-size: 14px;
      transform: translateX(-40px);
      opacity: 1;
    }

    .lock-code .icon-down {
      transform: translateX(-40px);
    }

    box-shadow: 0 0 8px 0 rgba(232, 237, 250, .6), 0 2px 4px 0 rgba(232, 237, 250, .5);
  }

  .code-content {
    background-color: #fafafa;
    border-top: 1px solid #eaeefb;
    overflow: hidden;
    transition: height .2s;

    .code-content-height {
      .code-user-desc {
        background: #ffffff;
        margin: 10px 10px 0 10px;
        padding: 5px 10px;
        font-size: 14px;
        line-height: 26px;
        border: 1px solid #ebebeb;
        border-radius: 3px;
      }

      > pre {
        background: none;

        > code {
          color: #3182bd;
        }
      }
    }
  }

  .lock-code {
    border-top: 1px solid #eaeefb;
    height: 44px;
    box-sizing: border-box;
    background-color: #fff;
    border-bottom-left-radius: 4px;
    border-bottom-right-radius: 4px;
    text-align: center;
    margin-top: -1px;
    color: #d3dce6;
    cursor: pointer;
    position: relative;
    line-height: 44px;
    color: #d3dce6;

    &:hover {
      background-color: #f9fafc;

      .lock-code-word {
        color: #409eff;
      }

      .icon-down {
        fill: #409eff;
      }
    }

    .icon-down {
      transform: translateX(0px);
      transition: all .1s;
    }

    text-align: center;

    .lock-code-word {
      font-size: 0px;
      margin-left: 15px;
      display: inline-block;
      transition: all .1s;
      opacity: 0;
    }
  }
}

::-webkit-scrollbar {
  width: 8px;
  background-color: #f5f5f5;
}

::-webkit-scrollbar-thumb {
  border-radius: 6px;
  background-color: #ccc;
}

::-webkit-scrollbar-track {
  border-radius: 6px;
  background-color: #f5f5f5;
}

之后便可以在文件中使用啦,/docs/.vuepress/components下创建demo.vue

<template>
  <div class="demo">
    <h2>创建组件文档模板</h2>
    <p>组件描述</p>
    <h3>组件功能名字</h3>
    <p>组件功能描述</p>
    <div class="component-wrapper">
      <div class="component-wrapper-demo">
        组件展示位置
      </div>
      <div class="code-content" style="height: 0;">
        <div class="code-content-height">
          <!-- <div class="code-user-desc">
            组件描述说明
          </div> -->
          <pre><code class="vue">{{codeStr}}</code></pre>
        </div>
      </div>
      <div class="lock-code" @click="showCode(0)" ref="xxx">
        <w-icon class="icon-down" :name="isShow[0] === false ? 'down' : 'up'"></w-icon>
        <span class="lock-code-word">{{isShow[0] === false ? '显示代码' : '隐藏代码'}}</span>
      </div>
    </div>

    <h3>attributes</h3>
    <p>组件参数说明后期扩展</p>
  </div>
</template>

<script>
  import WIcon from '../../../src/icon/icon'
  import mixin from '../mixin'
  export default {
    name: 'demo',
    mixins: [mixin],
    components: {
      WIcon,
    },
    data() {
      return {
        codeStr: `
          <g-button>默认按钮</g-button>
        `.replace(/^\s*/gm, '').trim(),
      }
    }
  }
</script>

<style lang="scss" scoped>

</style>

文档配置中引入此组件展示即可,效果如图:

image

可点击显示隐藏代码

二、高亮代码

在组件中插入代码想使得代码语法高亮可以用highlight插件

1. 安装

yarn add -D highlight.js

2. 全局引入

enhanceApp.js中 引入highlight插件,这里使用与element-ui一样的color-brewer主题

import './public/index.scss'
//代码高亮文件引入
import Vue from 'vue'
import hljs from 'highlight.js'
//样式文件,这里我选的是sublime样式,文件里面还有其他样式可供选择
import 'highlight.js/styles/color-brewer.css' 
Vue.directive('highlight',function (el) {
  let blocks = el.querySelectorAll('pre code');
      blocks.forEach((block)=>{
      hljs.highlightBlock(block)
  })
})
export default ({
                  Vue, // VuePress 正在使用的 Vue 构造函数
                  // options, // 附加到根实例的一些选项
                  // router, // 当前应用的路由实例
                  // siteData // 站点元数据
                }) => {
// ...做一些其他的应用级别的优化
}

3. 使用

之后在包装代码的外层div加上v-highlight指令,并在code标签标明代码模板类型为html/javascript/css

      <div class="code-content" v-highlight style="height: 0;">
        <div class="code-content-height">
          <!-- <div class="code-user-desc">
            组件描述说明
          </div> -->
          <pre><code class="html">{{codeStr}}</code></pre>
        </div>
      </div>

4. 效果

image

仿element-ui的风格,其他主题可以到highlight的官方文档中寻找highlight​github.com

总结

这是本人用vuepress写的UI框架文档,可供参考.🚲 EchoWheel UI​zyqq.github.io

感谢下面两个作者,如需删除请联系

作者:qfstudy
链接:https://segmentfault.com/a/1190000017265894
来源:SegmentFault 思否

作者:Adoins
链接:https://www.jianshu.com/p/1faeda421e74
来源:简书