Merge pull request #3 from opennms-forge/update/antora-default-ui

Update Antora Default UI

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}]
 
@@ -97,20 +98,21 @@ Now that you have Node.js installed, you can proceed with installing the Gulp CL
 You'll need the Gulp command-line interface (CLI) to run the build.
 The Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.
 
-You should install the Gulp CLI globally (which resolves to a location in your user directory if you're using nvm) using the following command:
+You can install the Gulp CLI globally (which resolves to a location in your user directory if you're using nvm) using the following command:
 
  $ npm install -g gulp-cli
 
 Verify the Gulp CLI is installed and on your PATH by running:
 
  $ gulp --version
 
-[TIP]
-====
 If you prefer to install global packages using Yarn, run this command instead:
 
  $ yarn global add gulp-cli
-====
+
+Alternately, you can use the `gulp` command that is installed by the project's dependencies.
+
+ $ $(npm bin)/gulp --version
 
 Now that you have the prerequisites installed, you can fetch and build the UI project.
 
@@ -183,6 +185,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.

docs/modules/ROOT/pages/add-fonts.adoc

@@ -3,12 +3,11 @@
 This page explains how to add new fonts to your UI.
 These instructions assume you've forked the default UI and are able to customize it.
 
-There are two steps involved:
+There are three steps involved:
 
 . Add the font to your UI project
 . Add a font-face declaration to your stylesheet
-
-You can then reference the font family in your stylesheet.
+. Use the new font in your stylesheet
 
 How you reference the font file in the font-face declaration depends on how you decide to manage it.
 You can manage the font with npm or download it manually and add it directly to your UI project.
@@ -41,8 +40,17 @@ Here are the steps involved.
 ----
 +
 The Gulp build recognizes the `~` URL prefix and copies the font from the npm package to the build folder (and hence bundle).
++
+You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
+
+. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
++
+[source,css]
+----
+@import "typeface-open-sans.css";
+----
 
-. Repeat the previous step for each font style and weight you want to use from that package.
+. Repeat the previous steps for each font style and weight you want to use from that package.
 . Change the CSS to use your newly imported font:
 +
 [source,css]
@@ -51,6 +59,8 @@ html {
   font-family: "Open Sans", sans;
 }
 ----
++
+TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
 
 . Test the new font by previewing your UI:
 
@@ -83,8 +93,17 @@ Create this folder if it does not exist.
 ----
 +
 Note that the path is a relative path starting from the [.path]_src/css_ folder to the [.path]_src/font_ folder.
++
+You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
 
-. Repeat the previous step for each font style and weight you want to use.
+. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
++
+[source,css]
+----
+@import "typeface-open-sans.css";
+----
+
+. Repeat the previous steps for each font style and weight you want to use.
 . Change the CSS to use your newly imported font:
 +
 [source,css]
@@ -93,6 +112,8 @@ html {
   font-family: "Open Sans", sans;
 }
 ----
++
+TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
 
 . Test the new font by previewing your UI:
 

docs/modules/ROOT/pages/templates.adoc

@@ -42,7 +42,8 @@ s| [[site]]site
 
 | site.path
 | The pathname (i.e., subpath) of the site.url under which the site is hosted (e.g., /docs).
-Only set if site.url is defined.
+This value is empty if site.url is not defined, has no path segment, or matches /.
+Can be removed from the site.url value using a helper (e.g., `deleteSuffix site.url site.path`)
 (since Antora 2.1)
 
 | site.title
@@ -51,6 +52,8 @@ Only set if site.url is defined.
 | site.components
 | A map of all the components in the site, keyed by component name.
 Properties of each component include name, title, url, latest, and versions.
+Properties of each version include name (since 2.3), version, displayVersion, prerelease (if set), title, url, asciidoc (since 2.3), and navigation.
+The navigation property on each version provides access to the navigation menu for that component version.
 
 | site.ui
 | Information about the site UI.
@@ -65,7 +68,8 @@ s| [[page]]page
 | Information about the current page.
 
 | page.title
-| The page title (also used as the primary heading).
+| The page title in HTML format (often used as the primary heading).
+This value may include inline HTML elements and XML character references.
 
 | page.contents
 | The main article content in HTML format.
@@ -90,7 +94,7 @@ Properties include name, title, url, latest, and versions.
 
 | page.componentVersion
 | Information about the component version for the current page.
-Properties include version, displayVersion, prerelease (if set), title, and url.
+Properties include name (since 2.3), version, displayVersion, prerelease (if set), title, url, and asciidoc (since 2.3).
 
 | page.module
 | The name of the module for the current page.
@@ -107,9 +111,10 @@ Each entry has the properties url, string, and missing.
 
 | page.breadcrumbs
 | An array of breadcrumb items that represent the current selection in the navigation tree.
+Includes text-only and external items.
 
 | page.navigation
-| A collection of navigation links for the current page.
+| The hierarchical navigation menu for the component version of the current page.
 Each navigation item contains the property `content` as well as the optional properties `url` and (child) `items`.
 
 | page.url
@@ -124,8 +129,18 @@ If there are multiple versions of the component, the canonical URL is the qualif
 If there's only a single version of the component, the canonical URL is the qualified URL of the current page.
 
 | page.editUrl
-| The URL to edit the current page (typically a web-based editor on the git host).
-The only hosts supported right now are github.com, gitlab.com, pagure.io, and bitbucket.org.
+| The URL to edit the current page (i.e., activates the web-based editor on the git host).
+This value is derived automatically for the hosts github.com, gitlab.com, pagure.io, and bitbucket.org, even if the repository is private.
+If the host is not recognized, or you want to customize the value, you can use the `edit_url` key on the content source in the playbook.
+
+The default UI shows an "Edit this Page" link that points to this URL unless the repository is private (i.e., `page.origin.private` is true) or `page.fileUri` is set.
+You can force this link to be shown by setting the environment variable `FORCE_SHOW_EDIT_PAGE_LINK` (e.g., `FORCE_SHOW_EDIT_PAGE_LINK=true`) or by customizing the logic in the UI template.
+
+| page.fileUri
+| The local file:// URI to edit the current page if the page originates from the local filesystem (i.e., the worktree).
+
+If this property is set, the default UI shows an "Edit this Page" link that points to this URI (instead of the `page.editUrl` value) unless the `CI` environment variable is set (e.g., `CI=true`).
+When the `CI` environment variable is set, the default UI ignores this property (since linking to a local file:// URI in a published site doesn't make any sense).
 
 | page.origin.private
 | This value will be true if the repository requires authentication or the repository URL embeds credentials.
@@ -140,13 +155,13 @@ Then, the "Edit the Page" link will not appear.
 | The page layout for the current page.
 
 | page.next
-| The next logical page in the navigation tree.
+| The next reachable page in the navigation tree (skips past text-only and external items).
 
 | page.previous
-| The previous logical page in the navigation tree.
+| The previous reachable page in the navigation tree (skips past text-only and external items).
 
 | page.parent
-| The parent page in the navigation tree. Will resolve to grandparent if parent item is not a page.
+| The parent page in the navigation tree (skips past text-only and external items).
 
 s| env
 | The map of environment variables (sourced from `process.env`).

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

@@ -1,5 +1,11 @@
 'use strict'
 
+// NOTE remove patch after upgrading from asciidoctor.js to @asciidoctor/core
+Error.call = (self, ...args) => {
+  const err = new Error(...args)
+  return Object.assign(self, { message: err.message, stack: err.stack })
+}
+
 const asciidoctor = require('asciidoctor.js')()
 const fs = require('fs-extra')
 const handlebars = require('handlebars')
@@ -11,27 +17,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 +53,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())
     )
 
@@ -89,17 +90,28 @@ 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 = {}) {
@@ -110,6 +122,19 @@ 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))
+  )
 }