Switch markdown parser to markdown-it

Marked was no longer actively maintained and had several bugs the new docs were hitting. The other good option here is Remark, which is a bit slower but more flexible.

Author: Mr0grog

gulpfile.babel.js

@@ -2,6 +2,7 @@ import gulp from 'gulp';
 import path from 'path';
 import Metalsmith from 'metalsmith';
 import _ from 'lodash';
+import markdownItAnchor from 'markdown-it-anchor';
 import util from 'util';
 import fs from 'fs';
 import hbars from './gulp/handlebars';
@@ -88,7 +89,18 @@ gulp.task('build', ['src:symlink-repos', "js:copy-vendor"], done => {
       ]
     }))
     .use(renameReadme)
-    .use($m.markdown())
+    .use($m.markdownit({
+      html: true,
+      linkify: true,
+      typographer: true
+    }).use(markdownItAnchor, {
+      // We can pre-generate the links & remove src/js/headingAnchorShortcut.js
+      // Off for now, though.
+      // permalink: true,
+      // permalinkClass: 'anchorShortcut',
+      // permalinkSymbol: '',
+      // permalinkBefore: true
+    }))
     .use($m.inPlace(_.extend({}, templateOptions, {
       pattern: '*.handlebars'
     })))

package.json

@@ -16,13 +16,14 @@
     "handlebars": "^4.0.2",
     "load-metalsmith-plugins": "^0.1.1",
     "lodash": "^3.10.1",
+    "markdown-it-anchor": "^2.5.0",
     "metalsmith": "git+https://github.com/stellar/metalsmith.git",
     "metalsmith-autoprefixer": "^1.1.0",
     "metalsmith-concat": "^3.0.3",
     "metalsmith-fingerprint": "^1.0.3",
     "metalsmith-in-place": "^1.3.1",
     "metalsmith-layouts": "^1.4.1",
-    "metalsmith-markdown": "^0.2.1",
+    "metalsmith-markdownit": "^0.3.0",
     "metalsmith-metadata": "0.0.1",
     "metalsmith-sass": "^1.3.0",
     "minimatch": "^2.0.10",