Implement an api to ignore content in certain tags

The parsers MarkBind uses parses content in html tags as html
or markdown respectively.
This makes it difficult to add custom components that utilize
conflicting syntax.

Let’s add an interface to ignore content in certain special tags.
This interface is also exposed to plugins as the getSpecialTags option.

docs/userGuide/usingPlugins.md

@@ -177,6 +177,26 @@ This allows files specified by the `src` attributes of `<puml>` tags to be watch
 }
 ```
 
+#### Special tags
+
+By default, content in html tags are parsed as html and markdown.
+
+However, you might want to create a plugin that has certain special tags containing conflicting syntax
+you do not wish to be parsed as html or markdown.
+
+You can implement the `getSpecialTags` method to blacklist the content in these special tags from parsing,
+removing such potential conflicts.
+
+- `getSpecialTags(pluginContext)`: Called to get link elements to be added to the head of the page.
+  - `pluginContext`: User provided parameters for the plugin. This can be specified in the `site.json`.
+  - Should return an array of string tag names to be blacklisted.
+
+<box type="important">
+Note however, that variable interpolation syntax <code>{<span>{</span> variable_name <span>}</span>}</code> will act as per normal.
+Meaning, the user would still be able to use variables in your special tags!
+</box>
+
+
 ### Advanced: Default plugins
 
 MarkBind has a set of default plugins that it uses to carry out some of its features. These are enabled by default for every project and should be left alone.

src/Site.js

@@ -8,6 +8,9 @@ const Promise = require('bluebird');
 const ProgressBar = require('progress');
 const walkSync = require('walk-sync');
 const MarkBind = require('./lib/markbind/src/parser');
+const injectHtmlParser2SpecialTags = require('./lib/markbind/src/patches/htmlparser2');
+const injectMarkdownItSpecialTags = require(
+  './lib/markbind/src/lib/markdown-it-shared/markdown-it-escape-special-tags');
 
 const _ = {};
 _.difference = require('lodash/difference');
@@ -525,6 +528,7 @@ class Site {
         .then(() => this.collectBaseUrl())
         .then(() => this.collectUserDefinedVariablesMap())
         .then(() => this.collectPlugins())
+        .then(() => this.collectPluginSpecialTags())
         .then(() => this.buildAssets())
         .then(() => this.buildSourceFiles())
         .then(() => this.copyMarkBindAsset())
@@ -736,6 +740,27 @@ class Site {
       .forEach(plugin => this.loadPlugin(plugin, true));
   }
 
+  /**
+   * Collects the special tags of the site's plugins, and injects them into the parsers.
+   */
+  collectPluginSpecialTags() {
+    const tagsToIgnore = new Set();
+
+    Object.values(this.plugins).forEach((plugin) => {
+      if (!plugin.getSpecialTags) return;
+
+      plugin.getSpecialTags(plugin.pluginsContext)
+        .forEach((tagName) => {
+          if (!tagName) return;
+
+          tagsToIgnore.add(tagName.toLowerCase());
+        });
+    });
+
+    injectHtmlParser2SpecialTags(tagsToIgnore);
+    injectMarkdownItSpecialTags(tagsToIgnore);
+  }
+
   /**
    * Renders all pages specified in site configuration file to the output folder
    */

src/lib/markbind/src/lib/markdown-it-shared/markdown-it-escape-special-tags.js

@@ -0,0 +1,95 @@
+const markdownIt = require('../markdown-it');
+
+/*
+ Custom patch for the api to escape content in certain special tags
+ Adapted from the default markdown-it html_block rule and replaces it.
+ */
+
+function escape_plugin(md, tagsToIgnore) {
+  const block_names = require('markdown-it/lib/common/html_blocks');
+  const HTML_OPEN_CLOSE_TAG_RE = require('markdown-it/lib/common/html_re').HTML_OPEN_CLOSE_TAG_RE;
+
+  const specialTagsRegex = Array.from(tagsToIgnore)
+    .concat(['script|pre|style'])
+    .join('|');
+  const startingSpecialTagRegex = new RegExp(`^<(${specialTagsRegex})(?=(\\s|>|$))`, 'i');
+  const endingSpecialTagRegex = new RegExp(`<\\/(${specialTagsRegex})>`, 'i');
+
+  const HTML_SEQUENCES = [
+    [ startingSpecialTagRegex, endingSpecialTagRegex, true ],
+    [ /^<!--/,        /-->/,   true ],
+    [ /^<\?/,         /\?>/,   true ],
+    [ /^<![A-Z]/,     />/,     true ],
+    [ /^<!\[CDATA\[/, /\]\]>/, true ],
+    [ new RegExp('^</?(' + block_names.join('|') + ')(?=(\\s|/?>|$))', 'i'), /^$/, true ],
+    [ new RegExp(HTML_OPEN_CLOSE_TAG_RE.source + '\\s*$'),  /^$/, false ]
+  ];
+
+
+  function escape_special_tags(state, startLine, endLine, silent) {
+    let i, nextLine, token, lineText,
+      pos = state.bMarks[startLine] + state.tShift[startLine],
+      max = state.eMarks[startLine];
+
+    // if it's indented more than 3 spaces, it should be a code block
+    if (state.sCount[startLine] - state.blkIndent >= 4) { return false; }
+
+    if (!state.md.options.html) { return false; }
+
+    if (state.src.charCodeAt(pos) !== 0x3C/* < */) { return false; }
+
+    lineText = state.src.slice(pos, max);
+
+    for (i = 0; i < HTML_SEQUENCES.length; i++) {
+      if (HTML_SEQUENCES[i][0].test(lineText)) { break; }
+    }
+
+    if (i === HTML_SEQUENCES.length) { return false; }
+
+    if (silent) {
+      // true if this sequence can be a terminator, false otherwise
+      return HTML_SEQUENCES[i][2];
+    }
+
+    nextLine = startLine + 1;
+
+    // If we are here - we detected HTML block.
+    // Let's roll down till block end.
+    if (!HTML_SEQUENCES[i][1].test(lineText)) {
+      for (; nextLine < endLine; nextLine++) {
+        if (state.sCount[nextLine] < state.blkIndent) { break; }
+
+        pos = state.bMarks[nextLine] + state.tShift[nextLine];
+        max = state.eMarks[nextLine];
+        lineText = state.src.slice(pos, max);
+
+        if (HTML_SEQUENCES[i][1].test(lineText)) {
+          if (lineText.length !== 0) { nextLine++; }
+          break;
+        }
+      }
+    }
+
+    state.line = nextLine;
+
+    token         = state.push('html_block', '', 0);
+    token.map     = [ startLine, nextLine ];
+    token.content = state.getLines(startLine, nextLine, state.blkIndent, true);
+
+    return true;
+  }
+
+  md.block.ruler.at('html_block', escape_special_tags, {
+    alt: [ 'paragraph', 'reference', 'blockquote' ]
+  });
+}
+
+/**
+ * Sets up the plugin with the provided tag names to ignore.
+ * Replaces any previously injected tags.
+ */
+function injectTags(tagsToIgnore) {
+  markdownIt.use(escape_plugin, tagsToIgnore);
+}
+
+module.exports = injectTags;