markdown线上部署方案

背景

在很多的后台管理系统或者门户系统中，经常会涉及到文档的展示，比如说vue的官方网站就存在大量的文档展示。这类文档一般是由PM写好的markdown文档，而前端开发人员就需要快速地将这些md文档部署到我们项目的页面上去。这就涉及到如何将md文档部署到网页上去，展示出和md编辑器一样的效果。

markdown展示

遇到上述需求，我们脑子里的第一想法是看是否由相关的插件，答案是肯定的。网络上有很多解析markdown文档的插件，比如说vue-markdown，marked.js，showdown，mavonEditor……我在项目中选用了vue-markdown，下面说说如何使用。

1. 要实现markdown，首先我们得安装text-loader解析导入的md文档

npm install text-loader --save-dev 
// or
yarn add text-loader

2. 进行webpack module配置

module:{
   
    rules:[
    {
   
       test: /.md$/,
       use: 'text-loader',        
    }
  ]
}

3. 安装md解析器vue-markdown

npm install vue-markdown --save-dev
// or
yarn add vue-markdown

4. 在Vue文件里面引入md文件

<template>
  <div>
    <h1>
      Ninecat-ui
    </h1>
    <vue-markdown>
      {
   {
    about }}
    </vue-markdown>
  </div>
</template>

<script>
import VueMarkdown from 'vue-markdown'
import about from '../../markdown/about.md'
export default {
   
  name: 'About',
  components: {
   
    VueMarkdown
  },
  data () {
   
    return {
   
      about: about
    }
  }
}
</script>

完成上面几步，我们就可以实现最核心的md展示功能了。

关于vue-markdown更多的用法，可参考官方文档vue-markdown

md文件中添加资源文件

在写md文档时，因为文档最后要部署到网页上。所以在写图片或者视频的路径时要采用线上的地址。

如果项目的静态资源就在项目的域名下，可采用以下写法：
显示图片

<img src="/static/images/5-vue/test.jpg" width="300" />

显示视频

<video src="/static/images/5-vue/20190509_191927.mp4" controls width="300" ></video>

显示能下载文件

源代码: <a href="/static/images/5-vue/test.rar" >下载</a> html文件: <a href="/static/images/5-vue/test.html" download>下载</a> js文件: <a href="/static/images/5-vue/test.js" >下载</a>

markdown样式

到上面这一步，我们仅仅是把使用md语法写的文档在网页上使用dom展示出来，现在的样式还是标签的基本样式，所以整体页面还比较丑，接下来我们美化一下。

关于md文档的css文件网上比较多，比如说vue官方文档的样式，Typora的各种主题样式，可以自己选择一个下载下来引入到项目当中。下载下来的文件也可以根据自己的需求进行修改。
Typora主题样式
有哪些Markdown的CSS样式表推荐？
简单又好看，你的 Markdown 文稿也能加上个性化主题

至此，我们完成了页面的美化。

文档目录

通常我们在网页上查看文档时都会有相应的文档目录，阅读时滑动文档，当前文档位置对应的目录样式也会跟着改变，点击目录跳转到文档相应的位置。

vue-markdown有自动生成目录的配置选项，我在项目中选择了自己来生成文档目录。

首先编写一个生成目录的组件DocMenu.