doc: use blockquotes for Stability: markers

Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (https://github.com/nodejs/node/pull/7729).

PR-URL: https://github.com/nodejs/node/pull/7757
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>

3 files changed, 40 insertions, 10 deletions

diff --git a/tools/doc/README.md b/tools/doc/README.md
index 1620d6c25a..e472c712dc 100644
--- a/tools/doc/README.md
+++ b/tools/doc/README.md
@@ -10,7 +10,7 @@ Each type of heading has a description block.
     added: v0.10.0
     -->
 
-        Stability: 3 - Stable
+    > Stability: 3 - Stable
 
     description and examples.
 
diff --git a/tools/doc/html.js b/tools/doc/html.js
index 75d5f08531..30bc3b5caa 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -150,15 +150,31 @@ function parseText(lexed) {
 // lists that come right after a heading are what we're after.
 function parseLists(input) {
   var state = null;
+  var savedState = [];
   var depth = 0;
   var output = [];
   output.links = input.links;
   input.forEach(function(tok) {
-    if (tok.type === 'code' && tok.text.match(/Stability:.*/g)) {
-      tok.text = parseAPIHeader(tok.text);
-      output.push({ type: 'html', text: tok.text });
+    if (tok.type === 'blockquote_start') {
+      savedState.push(state);
+      state = 'MAYBE_STABILITY_BQ';
       return;
     }
+    if (tok.type === 'blockquote_end' && state === 'MAYBE_STABILITY_BQ') {
+      state = savedState.pop();
+      return;
+    }
+    if ((tok.type === 'paragraph' && state === 'MAYBE_STABILITY_BQ') ||
+      tok.type === 'code') {
+      if (tok.text.match(/Stability:.*/g)) {
+        tok.text = parseAPIHeader(tok.text);
+        output.push({ type: 'html', text: tok.text });
+        return;
+      } else if (state === 'MAYBE_STABILITY_BQ') {
+        output.push({ type: 'blockquote_start' });
+        state = savedState.pop();
+      }
+    }
     if (state === null ||
       (state === 'AFTERHEADING' && tok.type === 'heading')) {
       if (tok.type === 'heading') {
diff --git a/tools/doc/json.js b/tools/doc/json.js
index 33bde6515b..f5bce30105 100644
--- a/tools/doc/json.js
+++ b/tools/doc/json.js
@@ -82,19 +82,19 @@ function doJSON(input, filename, cb) {
 
     // Immediately after a heading, we can expect the following
     //
-    // { type: 'code', text: 'Stability: ...' },
+    // { type: 'blockquote_start' }
+    // { type: 'paragraph', text: 'Stability: ...' },
+    // { type: 'blockquote_end' }
     //
     // a list: starting with list_start, ending with list_end,
     // maybe containing other nested lists in each item.
     //
-    // If one of these isnt' found, then anything that comes between
+    // If one of these isn't found, then anything that comes between
     // here and the next heading should be parsed as the desc.
     var stability;
     if (state === 'AFTERHEADING') {
-      if (type === 'code' &&
-          (stability = text.match(/^Stability: ([0-5])(?:\s*-\s*)?(.*)$/))) {
-        current.stability = parseInt(stability[1], 10);
-        current.stabilityText = stability[2].trim();
+      if (type === 'blockquote_start') {
+        state = 'AFTERHEADING_BLOCKQUOTE';
         return;
       } else if (type === 'list_start' && !tok.ordered) {
         state = 'AFTERHEADING_LIST';
@@ -129,6 +129,20 @@ function doJSON(input, filename, cb) {
       return;
     }
 
+    if (state === 'AFTERHEADING_BLOCKQUOTE') {
+      if (type === 'blockquote_end') {
+        state = 'AFTERHEADING';
+        return;
+      }
+
+      if (type === 'paragraph' &&
+          (stability = text.match(/^Stability: ([0-5])(?:\s*-\s*)?(.*)$/))) {
+        current.stability = parseInt(stability[1], 10);
+        current.stabilityText = stability[2].trim();
+        return;
+      }
+    }
+
     current.desc = current.desc || [];
     current.desc.push(tok);