chore(build): moving TOC headlines from metalsmith to markdown

Author: rodneyrehm

build/metalsmith/assets/website.css

@@ -230,10 +230,13 @@ main > article:first-of-type > header > h1 {
 }
 main .link-to-headline {
   text-decoration: none;
-  font-size: 65%;
   font-weight: normal;
   display: inline-block;
-  margin-right: 6px;
+  color: #999999;
+}
+main .link-to-headline:hover,
+main .link-to-headline:focus {
+  text-decoration: underline;
 }
 
 

build/metalsmith/metalsmith.markdown.js

@@ -5,6 +5,14 @@ const markdownOptions = {
   html: true,
 };
 
+const toc = require('markdown-it-toc-and-anchor').default;
+const tocOptions = {
+  // we are only interested in the headline mutations,
+  // as the TOC is built by a metalsmith plugin
+  toc: false,
+  anchorClassName: 'link-to-headline',
+};
+
 // see https://allyjs.io/contributing/docs.html#Notes-and-warnings
 const container = require('markdown-it-container');
 const containerOptions = {
@@ -29,5 +37,6 @@ const deflist = require('markdown-it-deflist');
 module.exports = function() {
   return markdown(markdownOptions)
     .use(container, 'note', containerOptions)
-    .use(deflist);
+    .use(deflist)
+    .use(toc, tocOptions);
 };

build/metalsmith/plugins/inject-examples.js

@@ -2,7 +2,6 @@
 const path = require('path');
 const URI = require('urijs');
 const cheerio = require('cheerio');
-const utils = require('./utils.js');
 
 function transform($, data, examples) {
   $('ul li strong').each(function() {
@@ -28,7 +27,6 @@ function transform($, data, examples) {
 
     const title = String($example('h1').first().text());
     const $title = $('<h1>').text('Example: ' + title);
-    utils.makeHeadlineLinkable($title, $);
 
     const jsbin = String($example('link[rel="jsbin"]').attr('href'));
     const jsbinEmbed = new URI(jsbin).segment('embed').query('output').toString();

build/metalsmith/plugins/prepare.transform.js

@@ -1,12 +1,10 @@
 
 'use strict';
 
-const utils = require('./utils.js');
-
 function extractData($, data) {
   // extract h1 to title
   if (!data.title) {
-    data.title = $('h1').text();
+    data.title = $('h1').text().replace(/^#\s+/, '');
     data.titleUrlEncoded = encodeURIComponent(data.title);
   }
 
@@ -51,12 +49,6 @@ function removeEmptyApiSections($/*, data*/) {
   });
 }
 
-function makeHeadlinesLinkable($/*, data*/) {
-  $('h1, h2, h3, h4, h5, h6').each(function() {
-    utils.makeHeadlineLinkable($(this), $);
-  });
-}
-
 function extractTableOfContents($, data) {
   // prepare Table Of Contents
   // inlining what metalsmith-autotoc would've done
@@ -65,7 +57,7 @@ function extractTableOfContents($, data) {
   $('h2').each(function() {
     const $this = $(this).clone();
     const $link = $this.find('.link-to-headline');
-    const id = $link.attr('id');
+    const id = $link.parent().attr('id');
     $link.remove();
     const text = $this.text();
 
@@ -93,7 +85,6 @@ module.exports = function($, data) {
   rewriteUrlsFromMdToHtml($, data);
 
   removeEmptyApiSections($, data);
-  makeHeadlinesLinkable($, data);
   extractTableOfContents($, data);
 
   convertCodeLanguageForPrism($, data);

build/metalsmith/plugins/utils.js

@@ -114,6 +114,7 @@
     "markdown-it": "^8.0.0",
     "markdown-it-container": "^2.0.0",
     "markdown-it-deflist": "^2.0.1",
+    "markdown-it-toc-and-anchor": "^4.1.1",
     "markdownlint": "^0.2.0",
     "metalsmith": "^2.1.0",
     "metalsmith-broken-link-checker": "^0.1.8",