build(aio): extract the title from the content if necessary

Documents can specify their title via the `title` or `name` jsdoc tags.

This change adds that, if neither are provided, the first `<h1>` element
is removed from the `renderedContent` and used for the title.

If there is still no title then it is set to the empty string and a warning
is logged.

aio/tools/transforms/angular.io-package/processors/convertToJson.js

@@ -1,4 +1,4 @@
-module.exports = function convertToJsonProcessor() {
+module.exports = function convertToJsonProcessor(log, createDocMessage) {
 
   return {
     $runAfter: ['checkUnbalancedBackTicks'],
@@ -8,13 +8,27 @@ module.exports = function convertToJsonProcessor() {
       const docTypes = this.docTypes;
       docs.forEach((doc) => {
         if (docTypes.indexOf(doc.docType) !== -1) {
-          const output = {
-            title: doc.title || doc.name,
-            contents: doc.renderedContent
-          };
-          doc.renderedContent = JSON.stringify(output, null, 2);
+          let title = doc.title || doc.name;
+          let contents = doc.renderedContent || '';
+
+          // If there is no title then try to extract it from the first h1 in the renderedContent
+          if (title === undefined) {
+            const match = /<h1[^>]*>(.+?)<\/h1>/.exec(contents);
+            if (match) {
+              title = match[1];
+            }
+          }
+
+          // If there is still no title then log a warning
+          if (title === undefined) {
+            title = '';
+            log.warn(createDocMessage('Title property expected', doc));
+          }
+
+          doc.renderedContent = JSON.stringify({ title, contents }, null, 2);
         }
       });
     }
   };
+
 };

aio/tools/transforms/angular.io-package/processors/convertToJson.spec.js

@@ -0,0 +1,55 @@
+var testPackage = require('../../helpers/test-package');
+var Dgeni = require('dgeni');
+
+describe('convertToJson processor', () => {
+  var dgeni, injector, processor, log;
+
+  beforeEach(function() {
+    dgeni = new Dgeni([testPackage('angular.io-package')]);
+    injector = dgeni.configureInjector();
+    processor = injector.get('convertToJsonProcessor');
+    log = injector.get('log');
+    processor.docTypes = ['test-doc'];
+  });
+
+  it('should be part of the dgeni package', () => {
+    expect(processor).toBeDefined();
+  });
+
+  it('should convert the renderedContent to JSON', () => {
+    const docs = [{
+      docType: 'test-doc',
+      title: 'The Title',
+      name: 'The Name',
+      renderedContent: 'Some Content'
+    }];
+    processor.$process(docs);
+    expect(JSON.parse(docs[0].renderedContent).title).toEqual('The Title');
+    expect(JSON.parse(docs[0].renderedContent).contents).toEqual('Some Content');
+  });
+
+  it('should get the title from name if no title is specified', () => {
+    const docs = [{ docType: 'test-doc', name: 'The Name' }];
+    processor.$process(docs);
+    expect(JSON.parse(docs[0].renderedContent).title).toEqual('The Name');
+  });
+
+  it('should get the title from the first `h1` if no title nor name is specified', () => {
+    const docs = [{ docType: 'test-doc', renderedContent: '<div><h1 class="title">Some title</h1><article><h1>Article 1</h1></article></div>' }];
+    processor.$process(docs);
+    expect(JSON.parse(docs[0].renderedContent).contents).toEqual('<div><h1 class="title">Some title</h1><article><h1>Article 1</h1></article></div>');
+    expect(JSON.parse(docs[0].renderedContent).title).toEqual('Some title');
+  });
+
+  it('should set missing titles to empty', () => {
+    const docs = [{ docType: 'test-doc' }];
+    processor.$process(docs);
+    expect(JSON.parse(docs[0].renderedContent).title).toBe('');
+  });
+
+  it('should log a warning', () => {
+    const docs = [{ docType: 'test-doc' }];
+    processor.$process(docs);
+    expect(log.warn).toHaveBeenCalled();
+  });
+});