当我们在完成一个任务时，会习惯性地留些文案来记录整个过程，一是方便我们以后追溯之前为何会这么做，会带来什么样的影响，以及以后该怎么做；二来可以方便新人在刚接触时能够快速了解。

如果使用记事本的方法来记忆，我们首先需要建立不同的文档，还要有一定的时间去处理不同的格式，只是偶尔的一次记载还好，如果我们常要做这些，有大量的文档需要处理，那这就需要花费大量的时间来维护，对于工作是很有影响的。

所以我们要有其它的方法来解决上面这个问题。

最简单的方法就是使用 markdown。

但是markdown需要有专门的编译运行才可，如果我们想在网页上直接看到的话还需要对它进行处理。

那我们可有办法对它进行处理吗？

答案是肯定的，通常我们可以使用 markdown-it来将它转成 html文档。

安装

nodejs 安装

npm install markdown-it --save

bower 安装

bower install markdown-it --save

除了以上两种方法，也可以选择 cdn https://cdnjs.com/libraries/markdown-it。

使用

下面是最简单的使用方法：

var md = require('markdown-it')();
var result = md.render('# 第一次使用);

当然，我们也可以做不同的配置，比如：

var md = require('markdown-it')({
  html: true,
  xhtmlOut: false,
});

那么，每个选项是什么含义呢？

• html: false 在源码中启用 HTML 标签
• xhtmlOut: false 使用 '/' 来闭合单标签 （比如 <br />）。这个选项只对完全的CommonMark 模式兼容。
• breaks: false 转换段落里的 '\n' 到
  。
• langPrefix: 'language-' 给围栏代码块的 CSS 语言前缀。对于额外的高亮代码非常有用。
• linkify: false 将类似 URL 的文本自动转换为链接。
• typographer: false 启用一些语言中立的替换 + 引号美化
• quotes: '“”‘’' 双 + 单引号替换对，当 typographer 启用时。或者智能引号等，可以是 String 或 Array。
• highlight: function (/str, lang/) { return ''; } 高亮函数，会返回转义的HTML。

语法高亮

var hljs = require('highlight.js');

// 通常的默认值们
var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(lang, str).value;
      } catch (__) {}
    }
    return ''; // 使用额外的默认转义
  }
});

如果遇到文档有 demo 要展示该如何做呢？

我们可以使用 markdown-it-container 来实现：

md.use(mdContainer, 'demo', {
    validate: function (param) {
      return !!param.trim().match(/^demo/);
    },
    render: function (tokens, idx) {
      const token = tokens[idx];
      if (token.nesting === 1) {
        return `<div className="demo">`;
      } else {
        return '</div>\n';
      }
    },
  })