Merge branch 'master' into ods-docs-ui

.eslintrc

@@ -9,6 +9,7 @@
       "exports": "always-multiline"
     }],
     "max-len": [1, 120, 2],
+    "no-void": "off",
     "spaced-comment": "off"
   }
 }

README.adoc

@@ -17,6 +17,7 @@
 :url-nodejs: https://nodejs.org
 :url-nvm: https://github.com/creationix/nvm
 :url-nvm-install: {url-nvm}#installation
+:url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
 
 image:{img-ci-status}[CI Status (GitLab CI), link={url-ci-pipelines}]
 
@@ -183,6 +184,22 @@ If you have the preview running, and you want to bundle without causing the prev
 
 The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
 
+==== Source Maps
+
+The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
+{url-source-maps}[Source maps] correlate these combined files with their original sources.
+
+This "`source mapping`" is accomplished by generating additional map files that make this association.
+These map files sit adjacent to the combined files in the build folder.
+The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.
+
+In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them.
+If you need to include source maps in the bundle, you can do so by setting the `SOURCEMAPS` environment varible to `true` when you run the bundle command:
+
+ $ SOURCEMAPS=true gulp bundle
+
+In this case, the bundle will include the source maps, which can be used for debuggging your production site.
+
 == Copyright and License
 
 Copyright (C) 2017-2019 OpenDevise Inc. and the Antora Project.

gulp.d/lib/gulp-prettier-eslint.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const log = require('fancy-log')
 const { obj: map } = require('through2')
 const PluginError = require('plugin-error')
 const prettierEslint = require('prettier-eslint')
@@ -17,9 +18,9 @@ module.exports = () => {
         .concat(' file')
         .concat(report.unchanged === 1 ? '' : 's')
         .concat(' unchanged')
-      console.log(`prettier-eslint: ${changed}; ${unchanged}`)
+      log(`prettier-eslint: ${changed}; ${unchanged}`)
     } else {
-      console.log(`prettier-eslint: left ${report.unchanged} file${report.unchanged === 1 ? '' : 's'} unchanged`)
+      log(`prettier-eslint: left ${report.unchanged} file${report.unchanged === 1 ? '' : 's'} unchanged`)
     }
   })
 

gulp.d/tasks/build-preview-pages.js

@@ -11,27 +11,17 @@ const requireFromString = require('require-from-string')
 const vfs = require('vinyl-fs')
 const yaml = require('js-yaml')
 
-const ASCIIDOC_ATTRIBUTES = {
-  experimental: '',
-  icons: 'font',
-  sectanchors: '',
-  'source-highlighter': 'highlight.js',
-}
+const ASCIIDOC_ATTRIBUTES = { experimental: '', icons: 'font', sectanchors: '', 'source-highlighter': 'highlight.js' }
 
-module.exports = (src, previewSrc, previewDest, sink = () => map(), layouts = {}) => () =>
+module.exports = (src, previewSrc, previewDest, sink = () => map()) => (done) =>
   Promise.all([
     loadSampleUiModel(previewSrc),
     toPromise(
-      merge(
-        compileLayouts(src, layouts),
-        registerPartials(src),
-        registerHelpers(src),
-        copyImages(previewSrc, previewDest)
-      )
+      merge(compileLayouts(src), registerPartials(src), registerHelpers(src), copyImages(previewSrc, previewDest))
     ),
   ])
-    .then(([baseUiModel]) => ({ ...baseUiModel, env: process.env }))
-    .then((baseUiModel) =>
+    .then(([baseUiModel, { layouts }]) => [{ ...baseUiModel, env: process.env }, layouts])
+    .then(([baseUiModel, layouts]) =>
       vfs
         .src('**/*.adoc', { base: previewSrc, cwd: previewSrc })
         .pipe(
@@ -57,11 +47,16 @@ module.exports = (src, previewSrc, previewDest, sink = () => map(), layouts = {}
               uiModel.page.contents = Buffer.from(doc.convert())
             }
             file.extname = '.html'
-            file.contents = Buffer.from(layouts[uiModel.page.layout](uiModel))
-            next(null, file)
+            try {
+              file.contents = Buffer.from(layouts.get(uiModel.page.layout)(uiModel))
+              next(null, file)
+            } catch (e) {
+              next(transformHandlebarsError(e, uiModel.page.layout))
+            }
           })
         )
         .pipe(vfs.dest(previewDest))
+        .on('error', (e) => done)
         .pipe(sink())
     )
 
@@ -79,6 +74,8 @@ function registerPartials (src) {
 }
 
 function registerHelpers (src) {
+  handlebars.registerHelper('resolvePage', resolvePage)
+  handlebars.registerHelper('resolvePageURL', resolvePageURL)
   return vfs.src('helpers/*.js', { base: src, cwd: src }).pipe(
     map((file, enc, next) => {
       handlebars.registerHelper(file.stem, requireFromString(file.contents.toString()))
@@ -87,19 +84,51 @@ function registerHelpers (src) {
   )
 }
 
-function compileLayouts (src, layouts) {
+function compileLayouts (src) {
+  const layouts = new Map()
   return vfs.src('layouts/*.hbs', { base: src, cwd: src }).pipe(
-    map((file, enc, next) => {
-      layouts[file.stem] = handlebars.compile(file.contents.toString(), { preventIndent: true })
-      next()
-    })
+    map(
+      (file, enc, next) => {
+        const srcName = path.join(src, file.relative)
+        layouts.set(file.stem, handlebars.compile(file.contents.toString(), { preventIndent: true, srcName }))
+        next()
+      },
+      function (done) {
+        this.push({ layouts })
+        done()
+      }
+    )
   )
 }
 
 function copyImages (src, dest) {
-  return vfs.src('**/*.{png,svg}', { base: src, cwd: src }).pipe(vfs.dest(dest))
+  return vfs
+    .src('**/*.{png,svg}', { base: src, cwd: src })
+    .pipe(vfs.dest(dest))
+    .pipe(map((file, enc, next) => next()))
+}
+
+function resolvePage (spec, context = {}) {
+  if (spec) return { pub: { url: resolvePageURL(spec) } }
+}
+
+function resolvePageURL (spec, context = {}) {
+  if (spec) return '/' + (spec = spec.split(':').pop()).slice(0, spec.lastIndexOf('.')) + '.html'
+}
+
+function transformHandlebarsError ({ message, stack }, layout) {
+  const m = stack.match(/^ *at Object\.ret \[as (.+?)\]/m)
+  const templatePath = `src/${m ? 'partials/' + m[1] : 'layouts/' + layout}.hbs`
+  const err = new Error(`${message}${~message.indexOf('\n') ? '\n^ ' : ' '}in UI template ${templatePath}`)
+  err.stack = [err.toString()].concat(stack.substr(message.length + 8)).join('\n')
+  return err
 }
 
 function toPromise (stream) {
-  return new Promise((resolve, reject) => stream.on('error', reject).on('finish', resolve))
+  return new Promise((resolve, reject, data = {}) =>
+    stream
+      .on('error', reject)
+      .on('data', (chunk) => chunk.constructor === Object && Object.assign(data, chunk))
+      .on('finish', () => resolve(data))
+  )
 }

gulp.d/tasks/build.js

@@ -24,6 +24,15 @@ module.exports = (src, dest, preview) => () => {
   const sourcemaps = preview || process.env.SOURCEMAPS === 'true'
   const postcssPlugins = [
     postcssImport,
+    (root, { messages, opts: { file } }) =>
+      Promise.all(
+        messages
+          .reduce((accum, { file: depPath, type }) => (type === 'dependency' ? accum.concat(depPath) : accum), [])
+          .map((importedPath) => fs.stat(importedPath).then(({ mtime }) => mtime))
+      ).then((mtimes) => {
+        const newestMtime = mtimes.reduce((max, curr) => (!max || curr > max ? curr : max))
+        if (newestMtime > file.stat.mtime) file.stat.mtimeMs = +(file.stat.mtime = newestMtime)
+      }),
     postcssUrl([
       {
         filter: '**/~typeface-*/files/*',
@@ -47,18 +56,30 @@ module.exports = (src, dest, preview) => () => {
     vfs
       .src('js/+([0-9])-*.js', { ...opts, sourcemaps })
       .pipe(uglify())
+      // NOTE concat already uses stat from newest combined file
       .pipe(concat('js/site.js')),
     vfs
       .src('js/vendor/*.js', { ...opts, read: false })
       .pipe(
         // see https://gulpjs.org/recipes/browserify-multiple-destination.html
         map((file, enc, next) => {
           if (file.relative.endsWith('.bundle.js')) {
-            file.contents = browserify(file.relative, { basedir: src, detectGlobals: false })
+            const mtimePromises = []
+            const bundlePath = file.path
+            browserify(file.relative, { basedir: src, detectGlobals: false })
               .plugin('browser-pack-flat/plugin')
-              .bundle()
-            file.path = file.path.slice(0, file.path.length - 10) + '.js'
-            next(null, file)
+              .on('file', (bundledPath) => {
+                if (bundledPath !== bundlePath) mtimePromises.push(fs.stat(bundledPath).then(({ mtime }) => mtime))
+              })
+              .bundle((bundleError, bundleBuffer) =>
+                Promise.all(mtimePromises).then((mtimes) => {
+                  const newestMtime = mtimes.reduce((max, curr) => (!max || curr > max ? curr : max))
+                  if (newestMtime > file.stat.mtime) file.stat.mtimeMs = +(file.stat.mtime = newestMtime)
+                  file.contents = bundleBuffer
+                  file.path = file.path.slice(0, file.path.length - 10) + '.js'
+                  next(bundleError, file)
+                })
+              )
           } else {
             fs.readFile(file.path, 'UTF-8').then((contents) => {
               file.contents = Buffer.from(contents)
@@ -69,17 +90,21 @@ module.exports = (src, dest, preview) => () => {
       )
       .pipe(buffer())
       .pipe(uglify()),
-    vfs.src('css/site.css', { ...opts, sourcemaps }).pipe(postcss(postcssPlugins)),
+    vfs
+      .src('css/site.css', { ...opts, sourcemaps })
+      .pipe(postcss((file) => ({ plugins: postcssPlugins, options: { file } }))),
     vfs.src('font/*.{ttf,woff*(2)}', opts),
     vfs
       .src('img/**/*.{gif,ico,jpg,png,svg}', opts)
       .pipe(
-        imagemin([
-          imagemin.gifsicle(),
-          imagemin.jpegtran(),
-          imagemin.optipng(),
-          imagemin.svgo({ plugins: [{ removeViewBox: false }] }),
-        ].reduce((accum, it) => it ? accum.concat(it) : accum, []))
+        imagemin(
+          [
+            imagemin.gifsicle(),
+            imagemin.jpegtran(),
+            imagemin.optipng(),
+            imagemin.svgo({ plugins: [{ removeViewBox: false }] }),
+          ].reduce((accum, it) => (it ? accum.concat(it) : accum), [])
+        )
       ),
     vfs.src('helpers/*.js', opts),
     vfs.src('layouts/*.hbs', opts),

gulp.d/tasks/pack.js

@@ -2,9 +2,10 @@
 
 const vfs = require('vinyl-fs')
 const zip = require('gulp-vinyl-zip')
+const path = require('path')
 
-module.exports = (src, dest, bundleName) => () =>
+module.exports = (src, dest, bundleName, onFinish) => () =>
   vfs
     .src('**/*', { base: src, cwd: src })
-    .pipe(zip.zip(`${bundleName}-bundle.zip`))
-    .pipe(vfs.dest(dest))
+    .pipe(zip.dest(path.join(dest, `${bundleName}-bundle.zip`)))
+    .on('finish', () => onFinish && onFinish(path.resolve(dest, `${bundleName}-bundle.zip`)))

gulpfile.js

@@ -3,6 +3,7 @@
 const { parallel, series, watch } = require('gulp')
 const createTask = require('./gulp.d/lib/create-task')
 const exportTasks = require('./gulp.d/lib/export-tasks')
+const log = require('fancy-log')
 
 const bundleName = 'ui'
 const buildDir = 'build'
@@ -53,7 +54,11 @@ const formatTask = createTask({
 const buildTask = createTask({
   name: 'build',
   desc: 'Build and stage the UI assets for bundling',
-  call: task.build(srcDir, destDir, process.argv.slice(2).some((name) => name.startsWith('preview'))),
+  call: task.build(
+    srcDir,
+    destDir,
+    process.argv.slice(2).some((name) => name.startsWith('preview'))
+  ),
 })
 
 const bundleBuildTask = createTask({
@@ -64,7 +69,12 @@ const bundleBuildTask = createTask({
 const bundlePackTask = createTask({
   name: 'bundle:pack',
   desc: 'Create a bundle of the staged UI assets for publishing',
-  call: task.pack(destDir, buildDir, bundleName),
+  call: task.pack(
+    destDir,
+    buildDir,
+    bundleName,
+    (bundlePath) => !process.env.CI && log(`Antora option: --ui-bundle-url ${bundlePath}`)
+  ),
 })
 
 const bundleTask = createTask({