diff --git a/aio/tools/transforms/examples-package/processors/render-examples.js b/aio/tools/transforms/examples-package/processors/render-examples.js
index ac777cf9d0..b90d5763f1 100644
--- a/aio/tools/transforms/examples-package/processors/render-examples.js
+++ b/aio/tools/transforms/examples-package/processors/render-examples.js
@@ -4,10 +4,11 @@ const { parseAttributes, renderAttributes } = require('../../helpers/utils');
* Search the renderedContent looking for code examples that have a path (and optionally a region) attribute.
* When they are found replace their content with the appropriate doc-region parsed previously from an example file.
*/
-module.exports = function renderExamples(getExampleRegion) {
+module.exports = function renderExamples(getExampleRegion, log, createDocMessage) {
return {
$runAfter: ['docs-rendered'],
$runBefore: ['writing-files'],
+ ignoreBrokenExamples: false,
$process: function(docs) {
docs.forEach(doc => {
if (doc.renderedContent) {
@@ -17,34 +18,41 @@ module.exports = function renderExamples(getExampleRegion) {
(original, openingTag, attributes, closingTag) => {
const attrMap = parseAttributes(attributes);
if (attrMap.path) {
- if (closingTag !== openingTag) {
- // The markdown renderer will wrap what it thinks is a paragraph in `
` and `
` tags.
- // If you do not leave a blank line between a paragraph of text and a `` then
- // the markdown renderer may add a paragraph marker "in-between" the opening and closing
- // tags of the code-example. For example:
- //
- // ```
- // Some paragraph
- //
- //
- //
- // ```
- //
- // will be rendered as:
- //
- // ```
- // Some paragraph
- //
- //
- //
- // ```
- throw new Error(
- 'Badly formed example: ' + original + ' - closing tag does not match opening tag.\n' +
- ' - Perhaps you forgot to put a blank line before the example?');
+ try {
+ if (closingTag !== openingTag) {
+ // The markdown renderer will wrap what it thinks is a paragraph in `` and `
` tags.
+ // If you do not leave a blank line between a paragraph of text and a `` then
+ // the markdown renderer may add a paragraph marker "in-between" the opening and closing
+ // tags of the code-example. For example:
+ //
+ // ```
+ // Some paragraph
+ //
+ //
+ //
+ // ```
+ //
+ // will be rendered as:
+ //
+ // ```
+ // Some paragraph
+ //
+ //
+ //
+ // ```
+ throw new Error(
+ 'Badly formed example: ' + original + ' - closing tag does not match opening tag.\n' +
+ ' - Perhaps you forgot to put a blank line before the example?');
+ }
+ // We found a path attribute so look up the example and rebuild the HTML
+ const exampleContent = getExampleRegion(doc, attrMap.path, attrMap.region);
+ return `<${openingTag}${renderAttributes(attrMap)}>\n${exampleContent}\n${openingTag}>`;
+ } catch(e) {
+ log.warn(createDocMessage(e.message, doc));
+ if (!this.ignoreBrokenExamples) {
+ throw e;
+ }
}
- // We found a path attribute so look up the example and rebuild the HTML
- const exampleContent = getExampleRegion(doc, attrMap.path, attrMap.region);
- return `<${openingTag}${renderAttributes(attrMap)}>\n${exampleContent}\n${openingTag}>`;
}
// No path attribute so just ignore this one
return original;
@@ -54,4 +62,3 @@ module.exports = function renderExamples(getExampleRegion) {
}
};
};
-
diff --git a/aio/tools/transforms/examples-package/processors/render-examples.spec.js b/aio/tools/transforms/examples-package/processors/render-examples.spec.js
index 362d8406f5..2fdf0bab9b 100644
--- a/aio/tools/transforms/examples-package/processors/render-examples.spec.js
+++ b/aio/tools/transforms/examples-package/processors/render-examples.spec.js
@@ -2,7 +2,7 @@ var testPackage = require('../../helpers/test-package');
var Dgeni = require('dgeni');
describe('renderExamples processor', () => {
- var injector, processor, exampleMap, collectExamples;
+ var injector, processor, exampleMap, collectExamples, log;
beforeEach(function() {
const dgeni = new Dgeni([testPackage('examples-package', true)]);
@@ -12,6 +12,7 @@ describe('renderExamples processor', () => {
processor = injector.get('renderExamples');
collectExamples = injector.get('collectExamples');
exampleMap = injector.get('exampleMap');
+ log = injector.get('log');
collectExamples.exampleFolders = ['examples'];
exampleMap['examples'] = {
@@ -97,6 +98,25 @@ describe('renderExamples processor', () => {
'Badly formed example: <' + CODE_TAG + ' path="test/url"> - closing tag does not match opening tag.\n' +
' - Perhaps you forgot to put a blank line before the example?');
});
+
+ it('should not throw if `ignoreBrokenExamples` is set to true', () => {
+ processor.ignoreBrokenExamples = true;
+ const docs = [
+ { renderedContent: `<${CODE_TAG} path="test/url">${CODE_TAG}>`},
+ { renderedContent: `<${CODE_TAG} path="test/url" region="missing">${CODE_TAG}>`},
+ { renderedContent: `<${CODE_TAG} path="missing/url">${CODE_TAG}>`}
+ ];
+ expect(() => processor.$process(docs)).not.toThrow();
+ expect(log.warn).toHaveBeenCalledWith(
+ 'Badly formed example: <' + CODE_TAG + ' path="test/url"> - closing tag does not match opening tag.\n' +
+ ' - Perhaps you forgot to put a blank line before the example? - doc');
+ expect(log.warn).toHaveBeenCalledWith(
+ 'Missing example region... relativePath: "test/url", region: "missing". - doc\n' +
+ 'Regions available are: "", "region-1" - doc');
+ expect(log.warn).toHaveBeenCalledWith(
+ 'Missing example file... relativePath: "missing/url". - doc\n' +
+ 'Example files can be found in the following relative paths: "examples" - doc');
+ });
})
);
});