update docs to reflect changes in Gulp build and Node requirements

5 files changed, 67 insertions, 80 deletions

diff --git a/README.adoc b/README.adoc
index ee2fe0b..b037252 100644
--- a/README.adoc
+++ b/README.adoc
@@ -47,7 +47,7 @@ A more comprehensive tutorial will be made available in the documentation.
 To preview and bundle the default UI, you need the following software on your computer:
 
 * {uri-git}[git] (command: `git`)
-* {uri-node}[Node 8] (command: `node`)
+* {uri-node}[Node] (command: `node`)
 * {uri-gulp}[Gulp CLI] (command: `gulp`)
 * {uri-yarn}[Yarn] (command: `yarn`)
 
@@ -59,31 +59,31 @@ First, make sure you have git installed.
 
 If not, {uri-git-dl}[download and install] the git package for your system.
 
-==== Node 8
+==== Node
 
-Next, make sure that you have Node 8 installed.
+Next, make sure that you have Node.js (herein "`Node`") installed.
 
  $ node --version
 
 If this command fails with an error, you don't have Node installed.
-If the command doesn't report a Node 8 version (e.g., v8.9.4), you don't have a suitable version of Node installed.
+If the command doesn't report a Node LTS version (e.g., v10.14.2), you don't have a suitable version of Node installed.
 
 While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node.
 Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
 
-Once you've installed nvm, open a new terminal and install Node 8 using the following command:
+Once you've installed nvm, open a new terminal and install Node 10 using the following command:
 
- $ nvm install 8
+ $ nvm install 10
 
 You can switch to this version of Node at any time using the following command:
 
- $ nvm use 8
+ $ nvm use 10
 
-To make Node 8 the default in new terminals, type:
+To make Node 10 the default in new terminals, type:
 
- $ nvm alias default 8
+ $ nvm alias default 10
 
-Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn.
+Now that you have Node 10 installed, you can proceed with installing the Gulp CLI and Yarn.
 
 ==== Gulp CLI
 
@@ -133,33 +133,30 @@ To build the UI and preview it in a local web server, run the `preview` command:
 
  $ gulp preview
 
-You'll see two URLs listed in the output of this command:
+You'll see a URL listed in the output of this command:
 
 ....
-[BS] Access URLs:
- ----------------------------------
-    Local: http://localhost:5252
- External: http://192.168.1.7:5252
- ----------------------------------
-[BS] Serving files from: build
-[BS] Watching files...
+[12:59:28] Starting 'preview:serve'...
+[12:59:28] Starting server...
+[12:59:28] Server started http://localhost:5252
+[12:59:28] Running server
 ....
 
-Navigate to the first URL to see the preview site.
+Navigate to that URL to view the preview site.
 
 While this command is running, any changes you make to the source files will be instantly reflected in the browser.
-This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser.
+This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
 
 Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
 === Package for Use with Antora
 
-If you need to package the UI in order to preview the UI on the real site in local development, run the following command:
+If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
 
- $ gulp pack
+ $ gulp bundle
 
 The UI bundle will be available at [.path]_build/ui-bundle.zip_.
-You can then point Antora at this bundle using the `--ui-bundle` command-line option.
+You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
 
 == Copyright and License
 
diff --git a/docs/modules/ROOT/pages/build-preview-ui.adoc b/docs/modules/ROOT/pages/build-preview-ui.adoc
index e386f05..3daab1c 100644
--- a/docs/modules/ROOT/pages/build-preview-ui.adoc
+++ b/docs/modules/ROOT/pages/build-preview-ui.adoc
@@ -26,45 +26,42 @@ The next two sections explain how to use these modes.
 
 To build the UI once for preview, then stop, execute the `build-preview` task using the following command:
 
- $ gulp build:preview
+ $ gulp preview:build
 
 This task pre-compiles the UI files into the [.path]_public_ directory.
 To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_).
 
 === Build Continuously
 
-To avoid the need to run the `build-preview` task over and over, you can use the `preview` command instead to have it run continuously.
+To avoid the need to run the `preview:build` task over and over, you can use the `preview` command instead to have it run continuously.
 This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`").
 
 To launch the preview server, execute the following command:
 
  $ gulp preview
 
-You'll see two URLs listed in the output of this command:
+You'll see a URL listed in the output of this command:
 
 ....
-[BS] Access URLs:
- ----------------------------------
-    Local: http://localhost:5252
- External: http://192.168.1.7:5252
- ----------------------------------
-[BS] Serving files from: build
-[BS] Watching files...
+[12:59:28] Starting 'preview:serve'...
+[12:59:28] Starting server...
+[12:59:28] Server started http://localhost:5252
+[12:59:28] Running server
 ....
 
-Navigate to the first one to see the preview site.
+Navigate to the URL to view the preview site.
 While this command is running, any changes you make to the source files will be instantly reflected in the browser.
-This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser.
+This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
 
 Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
 == Package for Previewing
 
-If you need to package the UI in order to preview the UI on the real site in local development, run the following command:
+If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
 
- $ gulp pack
+ $ gulp bundle
 
-The `pack` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
+The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
 
 The UI bundle will be available at [.path]_build/ui-bundle.zip_.
 You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index f4a227e..4258c3f 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -49,7 +49,7 @@ Handlebars (file extension: `.hbs`)::
 Templates contain placeholders (i.e., mustache expressions like `+{{{page.title}}}+`) into which content is injected from a model.
 They also accommodate simple logic expressions for repeating content or including it conditionally (e.g., `+{{#each navigation}}+`) as well as partials (e.g., `+{{> header}}+`).
 
-Gulp (script file: [.path]_gulpfile.js_)::
+Gulp (script file: [.path]_gulpfile.js/index.js_)::
 {uri-gulp}[Gulp] is a build tool for JavaScript projects.
 It configures a collection of tasks that can be used to perform automated tasks such as compiling files, running a preview server, or publishing a release.
 
@@ -91,7 +91,9 @@ Here's how the files are structured in the UI project:
 [.output]
 ....
 README.adoc
-gulpfile.js
+gulpfile.js/
+  index.js
+  ...
 package.json
 yarn.lock
 src/
@@ -123,16 +125,6 @@ src/
 preview-site-src/
   index.html
   ui-model.yml
-tasks/
-  lib/
-    gulp-prettier-eslint.js
-  build.js
-  build-preview.js
-  format.js
-  lint-css.js
-  lint-js.js
-  pack.js
-  preview.js
 ....
 
 A Gulp build is used to compile and assemble the UI project files into a UI bundle.
diff --git a/docs/modules/ROOT/pages/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc
index 28a0f7b..a4f4df2 100644
--- a/docs/modules/ROOT/pages/prerequisites.adoc
+++ b/docs/modules/ROOT/pages/prerequisites.adoc
@@ -6,23 +6,23 @@ endif::[]
 :idprefix:
 :idseparator: -
 // URIs:
-:uri-nvm: https://github.com/creationix/nvm
-:uri-node: https://nodejs.org
-:uri-gulp: http://gulpjs.com
-:uri-yarn: https://yarnpkg.com
-:uri-git: https://git-scm.com
-:uri-git-dl: {uri-git}/downloads
-:uri-nvm-install: {uri-nvm}#installation
+:url-nvm: https://github.com/creationix/nvm
+:url-node: https://nodejs.org
+:url-gulp: http://gulpjs.com
+:url-yarn: https://yarnpkg.com
+:url-git: https://git-scm.com
+:url-git-dl: {url-git}/downloads
+:url-node-releases: https://nodejs.org/en/about/releases/
 // These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not.
 
 An Antora UI project is based on tools built atop Node.js (aka Node), namely:
 
-* {uri-node}[Node] (command: `node`)
- ** {uri-nvm}[nvm] (optional, but strongly recommended)
-* {uri-gulp}[Gulp] (command: `gulp`)
-* {uri-yarn}[Yarn] (command: `yarn`)
+* {url-node}[Node] (command: `node`)
+ ** {url-nvm}[nvm] (optional, but strongly recommended)
+* {url-gulp}[Gulp] (command: `gulp`)
+* {url-yarn}[Yarn] (command: `yarn`)
 
-You also need {uri-git}[git] (command: `git`) to pull down the project and push updates to it.
+You also need {url-git}[git] (command: `git`) to pull down the project and push updates to it.
 
 == git
 
@@ -30,27 +30,28 @@ First, make sure you have git installed.
 
  $ git --version
 
-If not, {uri-git-dl}[download and install] the git package for your system.
+If not, {url-git-dl}[download and install] the git package for your system.
 
-== Node 8
+== Node
 
-Next, make sure that you have Node 8 installed.
-While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node.
-Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
+You need Node installed on your machine to use Antora, including the default UI.
+Antora follows Node's release schedule, so we advise that you choose an active long term support (LTS) release of Node.
+We recommend using the latest active Node LTS version.
+While you can use other versions of Node, Antora is only tested against LTS releases.
 
-Once you've installed nvm, open a new terminal and install Node 8 using the following command:
+To check whether you have Node installed, and which version, open a terminal and type:
 
- $ nvm install 8
+ $ node --version
 
-You can switch to this version of Node at any time using the following command:
+You should see a version string, such as:
 
- $ nvm use 8
+ v10.14.2
 
-To make Node 8 the default in new terminals, type:
+If the command fails with an error, it means you don't have Node installed.
+The best way to install Node is to use nvm (Node Version Manager).
+Refer to xref:antora:install:linux-requirements.adoc#install-nvm[Install nvm and Node (Linux)], xref:antora:install:macos-requirements.adoc#install-nvm[Install nvm and Node (macOS)], or xref:antora:install:windows-requirements.adoc#install-nvm[Install nvm and Node (Windows)] for instructions.
 
- $ nvm alias default 8
-
-Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn.
+Once you have Node installed, you can proceed with installing Gulp's CLI and Yarn.
 
 == Gulp CLI
 
diff --git a/docs/modules/ROOT/pages/set-up-project.adoc b/docs/modules/ROOT/pages/set-up-project.adoc
index b413de6..31dfd73 100644
--- a/docs/modules/ROOT/pages/set-up-project.adoc
+++ b/docs/modules/ROOT/pages/set-up-project.adoc
@@ -53,15 +53,15 @@ You should see:
 
 [.output]
 ....
-lint:css
-lint:js
+default
+clean
 lint
 format
 build
-build:preview
+bundle
+bundle:pack
 preview
-pack
-default
+preview:build
 ....
 
 We'll explain what each of these tasks are for and when to use them.