Implement an api to ignore text in certain tags

docs/userGuide/usingPlugins.md

@@ -178,6 +178,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 during initial site generation to blacklist special tags.
+  - `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, with each tag name being at least 2 characters long.
+
+<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/Page.js

@@ -665,7 +665,7 @@ class Page {
         + `${pageNavHeadingHTML}\n`
         + '</nav>\n'
         + '</div>\n'
-        + '</nav>\n', { indent_size: 2 });
+        + '</nav>\n', Page.htmlBeautifyOptions);
     }
   }
 
@@ -756,10 +756,10 @@ class Page {
     if (pageSection.length === 0) {
       return;
     }
-    this.pageSectionsHtml[section] = htmlBeautify($.html(section), { indent_size: 2 })
+    this.pageSectionsHtml[section] = htmlBeautify($.html(section), Page.htmlBeautifyOptions)
       .trim();
     pageSection.remove();
-    this.content = htmlBeautify($.html(), { indent_size: 2 });
+    this.content = htmlBeautify($.html(), Page.htmlBeautifyOptions);
   }
 
   collectAllPageSections() {
@@ -804,7 +804,7 @@ class Page {
         .then(result => markbinder.processDynamicResources(this.sourcePath, result))
         .then(result => MarkBind.unwrapIncludeSrc(result))
         .then((result) => {
-          this.content = htmlBeautify(result, { indent_size: 2 });
+          this.content = htmlBeautify(result, Page.htmlBeautifyOptions);
 
           const newBaseUrl = Page.calculateNewBaseUrl(this.sourcePath, this.rootPath, this.baseUrlMap);
           const baseUrl = newBaseUrl ? `${this.baseUrl}/${newBaseUrl}` : this.baseUrl;
@@ -823,7 +823,7 @@ class Page {
 
           return fs.outputFileAsync(this.resultPath, htmlBeautify(
             this.template.render(this.prepareTemplateData()),
-            { indent_size: 2 },
+            Page.htmlBeautifyOptions,
           ));
         })
         .then(() => {
@@ -1080,7 +1080,7 @@ class Page {
             baseUrl,
             hostBaseUrl,
           });
-          return fs.outputFileAsync(resultPath, htmlBeautify(content, { indent_size: 2 }));
+          return fs.outputFileAsync(resultPath, htmlBeautify(content, Page.htmlBeautifyOptions));
         })
         .then(() => {
           // Recursion call to resolve nested dependency

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,35 @@ 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);
+    Page.htmlBeautifyOptions = {
+      indent_size: 2,
+      content_unformatted: ['pre', ...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;