docs: use frontmatter for man page generation

Update the `docs-build.js` script to parse the name, man page section,
and description out of the frontmatter and use that for the generated
man page.  This helps avoid repetition between the frontmatter section
and the body of the page itself.

Update the docs pages themselves to remove the H1 (title) and H2
(description).  Finally, ensure that the frontmatter begins in column
0 on each page.

1 files changed, 14 insertions, 2 deletions

diff --git a/scripts/docs-build.js b/scripts/docs-build.js
index 390ea20be..89471a1f1 100644
--- a/scripts/docs-build.js
+++ b/scripts/docs-build.js
@@ -10,16 +10,28 @@ var dest = args[1] || src
 fs.readFile(src, 'utf8', function (err, data) {
   if (err) return console.log(err)
 
+  function frontmatter (match, p1) {
+    const fm = { }
+
+    p1.split(/\r?\n/).forEach((kv) => {
+      let result = kv.match(/^([^\s:]+):\s*(.*)/)
+      if (result) {
+        fm[result[1]] = result[2]
+      }
+    })
+
+    return `# ${fm['title']}(${fm['section']}) - ${fm['description']}`
+  }
+
   function replacer (match, p1) {
     return 'npm help ' + p1.replace(/npm /, '')
   }
 
   var result = data.replace(/@VERSION@/g, npm.version)
-    .replace(/^---([\s\S]+?)---/g, '')
+    .replace(/^---\n([\s\S]+\n)---/, frontmatter)
     .replace(/\[([^\]]+)\]\(\/cli-commands\/([^)]+)\)/g, replacer)
     .replace(/\[([^\]]+)\]\(\/configuring-npm\/([^)]+)\)/g, replacer)
     .replace(/\[([^\]]+)\]\(\/using-npm\/([^)]+)\)/g, replacer)
-    .replace(/(# .*)\s+(## (.*))/g, '$1 - $3')
     .trim()
 
   fs.writeFile(dest, marked(result), 'utf8', function (err) {