Allow full content override from highlighter

README.md

@@ -119,6 +119,7 @@ var md = require('markdown-it')({
 
   // Highlighter function. Should return escaped HTML,
   // or '' if the source string is not changed and should be escaped externaly.
+  // If result starts with <pre... internal wrapper is skipped.
   highlight: function (/*str, lang*/) { return ''; }
 });
 ```
@@ -149,15 +150,31 @@ var md = require('markdown-it')({
       } catch (__) {}
     }
 
-    try {
-      return hljs.highlightAuto(str).value;
-    } catch (__) {}
-
     return ''; // use external default escaping
   }
 });
 ```
 
+Or with full wrapper override (if you need assign class to <pre>):
+
+```js
+var hljs = require('highlight.js') // https://highlightjs.org/
+
+// Actual default values
+var md = require('markdown-it')({
+  highlight: function (str, lang) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return '<pre class="hljs"><code>' +
+               hljs.highlight(lang, str).value +
+               '</code></pre>';
+      } catch (__) {}
+    }
+
+    return '<pre class="hljs"><code>' + md.utils.esccapeHtml(str) + '</code></pre>';
+  }
+});
+```
 
 ### Linkify
 

lib/index.js

@@ -158,7 +158,8 @@ function normalizeLinkText(url) {
  *   `['«\xA0', '\xA0»', '‹\xA0', '\xA0›']` for French (including nbsp).
  * - __highlight__ - `null`. Highlighter function for fenced code blocks.
  *   Highlighter `function (str, lang)` should return escaped HTML. It can also
- *   return empty string if the source was not changed and should be escaped externaly.
+ *   return empty string if the source was not changed and should be escaped
+ *   externaly. If result starts with <pre... internal wrapper is skipped.
  *
  * ##### Example
  *
@@ -190,14 +191,32 @@ function normalizeLinkText(url) {
  *       } catch (__) {}
  *     }
  *
- *     try {
- *       return hljs.highlightAuto(str).value;
- *     } catch (__) {}
- *
  *     return ''; // use external default escaping
  *   }
  * });
  * ```
+ *
+ * Or with full wrapper override (if you need assign class to <pre>):
+ *
+ * ```javascript
+ * var hljs = require('highlight.js') // https://highlightjs.org/
+ *
+ * // Actual default values
+ * var md = require('markdown-it')({
+ *   highlight: function (str, lang) {
+ *     if (lang && hljs.getLanguage(lang)) {
+ *       try {
+ *         return '<pre class="hljs"><code>' +
+ *                hljs.highlight(lang, str).value +
+ *                '</code></pre>';
+ *       } catch (__) {}
+ *     }
+ *
+ *     return '<pre class="hljs"><code>' + md.utils.esccapeHtml(str) + '</code></pre>';
+ *   }
+ * });
+ * ```
+ *
  **/
 function MarkdownIt(presetName, options) {
   if (!(this instanceof MarkdownIt)) {

lib/presets/commonmark.js

@@ -22,7 +22,8 @@ module.exports = {
     quotes: '\u201c\u201d\u2018\u2019', /* “”‘’ */
 
     // Highlighter function. Should return escaped HTML,
-    // or '' if input not changed
+    // or '' if the source string is not changed and should be escaped externaly.
+    // If result starts with <pre... internal wrapper is skipped.
     //
     // function (/*str, lang*/) { return ''; }
     //

lib/presets/default.js

@@ -22,7 +22,8 @@ module.exports = {
     quotes: '\u201c\u201d\u2018\u2019', /* “”‘’ */
 
     // Highlighter function. Should return escaped HTML,
-    // or '' if input not changed
+    // or '' if the source string is not changed and should be escaped externaly.
+    // If result starts with <pre... internal wrapper is skipped.
     //
     // function (/*str, lang*/) { return ''; }
     //

lib/presets/zero.js

@@ -23,7 +23,8 @@ module.exports = {
     quotes: '\u201c\u201d\u2018\u2019', /* “”‘’ */
 
     // Highlighter function. Should return escaped HTML,
-    // or '' if input not changed
+    // or '' if the source string is not changed and should be escaped externaly.
+    // If result starts with <pre... internal wrapper is skipped.
     //
     // function (/*str, lang*/) { return ''; }
     //

lib/renderer.js

@@ -45,6 +45,10 @@ default_rules.fence = function (tokens, idx, options, env, slf) {
     highlighted = escapeHtml(token.content);
   }
 
+  if (highlighted.indexOf('<pre') === 0) {
+    return highlighted + '\n';
+  }
+
   return  '<pre><code' + slf.renderAttrs(token) + '>'
         + highlighted
         + '</code></pre>\n';

test/misc.js

@@ -45,7 +45,7 @@ describe('API', function () {
   it('highlight', function () {
     var md = markdownit({
       highlight: function (str) {
-        return '==' + str + '==';
+        return '<pre><code>==' + str + '==</code></pre>';
       }
     });