build(aio): do not HTML format code-example contents (#15554)

The markdown renderer passes its output through an HTML pretty printer.
While this is good in most cases, it makes a mess of elements that expect
their content to be left untouched.

The pretty printer already ignores `pre` tags (and other built-ins) by
default. This fix allows us to specify other tags that should be left
alone.

Further it actually specifies this option for `code-example` and `code-pane`
tags, which expect to contain preformatted content.

aio/content/marketing/test.html

@@ -6,7 +6,7 @@
 <code-tabs >
   <code-pane title='TS code file' language='ts'>class {
   foo(param: string) {}
-  }</code-pane>
+}</code-pane>
   <code-pane title='HTML content file' language='html'>&lt;h1&gt;Heading&lt;/h1&gt;</code-pane>
   <code-pane title='JSON data file' language='json' class='is-anti-pattern'>{ "key": "value" }</code-pane>
 </code-tabs>
@@ -16,7 +16,7 @@
 <code-tabs linenums='true'>
   <code-pane title='TS code file' language='ts'>class {
   foo(param: string) {}
-  }</code-pane>
+}</code-pane>
   <code-pane title='HTML content file' language='html'>&lt;h1&gt;Heading&lt;/h1&gt;</code-pane>
   <code-pane title='JSON data file' language='json' class='is-anti-pattern'>{ "key": "value" }</code-pane>
 </code-tabs>
@@ -26,7 +26,7 @@
 <code-tabs >
   <code-pane title='TS code file' language='ts'>class {
   foo(param: string) {}
-  }</code-pane>
+}</code-pane>
   <code-pane title='HTML content file' language='html' linenums='true'>&lt;h1&gt;Heading&lt;/h1&gt;</code-pane>
   <code-pane title='JSON data file' language='json' class='is-anti-pattern'>{ "key": "value" }</code-pane>
 </code-tabs>

aio/package.json

@@ -38,7 +38,6 @@
     "@angular/router": "next",
     "@angular/service-worker": "^1.0.0-beta.8",
     "core-js": "^2.4.1",
-    "rho": "https://github.com/petebacondarwin/rho#master",
     "rxjs": "^5.2.0",
     "zone.js": "^0.8.4"
   },
@@ -53,6 +52,7 @@
     "dgeni-packages": "0.17.0",
     "entities": "^1.1.1",
     "firebase-tools": "^3.2.1",
+    "html": "^1.0.0",
     "jasmine-core": "~2.5.2",
     "jasmine-spec-reporter": "~3.2.0",
     "karma": "~1.4.1",
@@ -63,6 +63,7 @@
     "karma-jasmine-html-reporter": "^0.2.2",
     "lodash": "^4.17.4",
     "protractor": "~5.1.0",
+    "rho": "https://github.com/petebacondarwin/rho#master",
     "rimraf": "^2.6.1",
     "ts-node": "~2.0.0",
     "tslint": "~4.5.0",

aio/transforms/angular.io-package/index.js

@@ -201,7 +201,7 @@ module.exports =
 
         // Configure nunjucks rendering of docs via templates
         .config(function(
-            renderDocsProcessor, versionInfo, templateFinder, templateEngine, getInjectables) {
+            renderDocsProcessor, versionInfo, templateFinder, templateEngine, getInjectables, renderMarkdown) {
 
           // Where to find the templates for the doc rendering
           templateFinder.templateFolders = [TEMPLATES_PATH];
@@ -228,6 +228,12 @@ module.exports =
           renderDocsProcessor.helpers.relativePath = function(from, to) {
             return path.relative(from, to);
           };
+
+          // Tell the HTML formatter not to format code-example blocks
+          renderMarkdown.unformattedTags = [
+            'code-example',
+            'code-pane'
+          ];
         })
 
 

aio/transforms/rho-package/services/renderMarkdown.js

@@ -1,4 +1,10 @@
-var rho = require('rho');
+const rho = require('rho');
+const { prettyPrint } = require('html');
+
+const defaultUnformattedTags = [
+  'a', 'span', 'bdo', 'em', 'strong', 'dfn', 'code', 'samp', 'kbd', 'var', 'cite', 'abbr', 'acronym',
+  'q', 'sub', 'sup', 'tt', 'i', 'b', 'big', 'small', 'u', 's', 'strike', 'font', 'ins', 'del', 'pre',
+  'address', 'dt', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
 
 /**
  * @dgService renderMarkdown
@@ -45,11 +51,18 @@ module.exports = function renderMarkdown() {
 
     if (isBlock) compiler.out.push('<div>');
     compiler.out.push(walk.substring(startIdx, endIdx + 1));
-    if (isBlock) compiler.out.push('</div>');
+    if (isBlock) compiler.out.push('</div>\n');
 
     walk.startFrom(endIdx + 2);
     return true;
   };
 
-  return function renderMarkdownImpl(content) { return rho.toHtml(content, true); };
+  renderMarkdownImpl.unformattedTags = [];
+
+  return renderMarkdownImpl;
+
+  function renderMarkdownImpl(content) {
+    const rawHtml = new rho.BlockCompiler(rho.options).toHtml(content);
+    return prettyPrint(rawHtml, { indent_size: 2, unformatted: [...defaultUnformattedTags, ...renderMarkdownImpl.unformattedTags]});
+  };
 };

aio/transforms/rho-package/services/renderMarkdown.spec.js

@@ -1,7 +1,11 @@
 const renderMarkdownFactory = require('./renderMarkdown');
-const renderMarkdown = renderMarkdownFactory();
 
 describe('rho: renderMarkdown service', () => {
+  let renderMarkdown;
+  beforeEach(() => {
+    renderMarkdown = renderMarkdownFactory();
+  });
+
   it('should convert markdown to HTML', () => {
     const content = '# heading 1\n' +
         '\n' +
@@ -17,13 +21,13 @@ describe('rho: renderMarkdown service', () => {
         '<ul>\n' +
         '  <li>List item 1</li>\n' +
         '  <li>List item 2</li>\n' +
-        '</ul>\n');
+        '</ul>');
   });
 
   it('should not process markdown inside inline tags', () => {
     const content = '# heading {@link some_url_path}';
     const output = renderMarkdown(content);
-    expect(output).toEqual('<h1>heading {@link some_url_path}</h1>\n');
+    expect(output).toEqual('<h1>heading {@link some_url_path}</h1>');
   });
 
   it('should not put block level inline tags inside paragraphs', () => {
@@ -36,6 +40,13 @@ describe('rho: renderMarkdown service', () => {
     expect(output).toEqual(
         '<p>A paragraph.</p>\n' +
         '<div>{@example blah **blah** blah }</div>\n' +
-        '<p>Another paragraph</p>\n');
+        '<p>Another paragraph</p>');
+  });
+
+  it('should not format the contents of tags marked as unformatted ', () => {
+    renderMarkdown.unformattedTags = ['code-example'];
+    const content = '<code-example>\n  abc\n  def\n</code-example>';
+    const output = renderMarkdown(content);
+    expect(output).toEqual('<code-example>\n  abc\n  def\n</code-example>');
   });
 });

aio/yarn.lock

@@ -2604,7 +2604,7 @@ html-webpack-plugin@^2.19.0:
     pretty-error "^2.0.2"
     toposort "^1.0.0"
 
-html@*:
+html@*, html@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/html/-/html-1.0.0.tgz#a544fa9ea5492bfb3a2cca8210a10be7b5af1f61"
   dependencies:
@@ -5781,14 +5781,10 @@ typedarray@^0.0.6:
   version "0.0.6"
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
 
-typescript@2.2.0:
+typescript@2.2.0, "typescript@>=2.0.0 <2.3.0":
   version "2.2.0"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.2.0.tgz#626f2fc70087d2480f21ebb12c1888288c8614e3"
 
-"typescript@>=2.0.0 <2.3.0":
-  version "2.1.6"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.1.6.tgz#40c7e6e9e5da7961b7718b55505f9cac9487a607"
-
 typescript@^1.7.5:
   version "1.8.10"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-1.8.10.tgz#b475d6e0dff0bf50f296e5ca6ef9fbb5c7320f1e"