revise documentation for accuracy

9 files changed, 128 insertions, 93 deletions

diff --git a/docs/antora.yml b/docs/antora.yml
index aa929d2..1807fb2 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -1,5 +1,5 @@
 name: antora-ui-default
-title: Antora UI
+title: Antora Default UI
 version: master
 nav:
 - modules/ROOT/nav.adoc
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 5d0b702..1c72071 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1,7 +1,7 @@
-.xref:index.adoc[Antora UI]
-* xref:development-workflow.adoc[UI Development Best Practices]
-* xref:install-development-prerequisites.adoc[Install Development Prerequisites]
-* xref:set-up-existing-project.adoc[Set up an Existing UI Project]
+.xref:index.adoc[Antora Default UI]
+* xref:prerequisites.adoc[UI Development Prerequisites]
+* xref:set-up-project.adoc[Set up a UI Project]
+* xref:build-preview-ui.adoc[Build and Preview the UI]
 * xref:templates.adoc[Work with the Handlebars Templates]
 * xref:stylesheets.adoc[Work the CSS Stylesheets]
-* xref:build-local-project.adoc[Build a UI Project for Local Preview]
+* xref:development-workflow.adoc[UI Development Workflow]
diff --git a/docs/modules/ROOT/pages/build-local-project.adoc b/docs/modules/ROOT/pages/build-preview-ui.adoc
index 558794b..cc44296 100644
--- a/docs/modules/ROOT/pages/build-local-project.adoc
+++ b/docs/modules/ROOT/pages/build-preview-ui.adoc
@@ -1,8 +1,8 @@
-= Build a UI Project for Local Previewing
+= Build a UI Project for Local Preview
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
 :experimental:
@@ -10,8 +10,9 @@ endif::[]
 == Build Preview Site
 
 Once you've modified the site UI, the first thing you'll want to do is check out how it looks.
-That's what the files in the [.path]_preview-site/_ folder are for.
-This folder contains HTML file fragments that provide a representative sample of content from the site (saving you from having to generate the whole site just to test the UI).
+That's what the files in the [.path]_preview-site-src/_ folder are for.
+This folder contains HTML file fragments that provide a representative sample of content from the site.
+The preview saves you from having to generate the whole site just to test the UI.
 These files should give you an idea of how the UI will look when applied to the actual site.
 
 The pages in the preview site are assembled using the Handlebars templates and link to the pre-compiled asset files (emulating the behavior of the site generator).
@@ -27,8 +28,8 @@ To build the UI once for preview, then stop, execute the `build-preview` task us
 
  $ gulp build:preview
 
-This task pre-compiles the UI files into the [.path]_build/preview-site/./_ directory.
-To view the preview pages, navigate to the HTML pages in the [.path]_build_ directory using your browser (e.g., [.path]_build/index.html_).
+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
 
@@ -66,4 +67,4 @@ If you need to package the UI in order to preview the UI on the real site in loc
 The `pack` 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 `--theme-archive` flag.
+You can then point Antora at this bundle using the `--ui-bundle` command-line option.
diff --git a/docs/modules/ROOT/pages/development-workflow.adoc b/docs/modules/ROOT/pages/development-workflow.adoc
index 2d9b787..9ce6fc0 100644
--- a/docs/modules/ROOT/pages/development-workflow.adoc
+++ b/docs/modules/ROOT/pages/development-workflow.adoc
@@ -2,7 +2,7 @@
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
 
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index cf6794d..359fc24 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -1,17 +1,12 @@
 = Antora Default UI
 // Settings:
-:toc:
-:toc-title: Contents
 :idprefix:
 :idseparator: -
 :experimental:
 :hide-uri-scheme:
-ifndef::env-github[:icons: font]
-ifdef::env-github[]
-:important-caption: :exclamation:
-endif::[]
 // URIs:
-:uri-project: https://gitlab.com/antora/antora-ui-default
+:uri-antora: https://antora.org
+:uri-repo: https://gitlab.com/antora/antora-ui-default
 :uri-preview: https://antora.gitlab.io/antora-ui-default
 :uri-hbs: http://handlebarsjs.com
 :uri-gulp: http://gulpjs.com
@@ -23,12 +18,11 @@ endif::[]
 :uri-git: https://git-scm.com
 :uri-git-dl: {uri-git}/downloads
 
-
-This {uri-project}[project] produces the {uri-preview}[default Antora UI bundle] for a documentation site.
-It contains the UI assets (page templates, CSS, JavaScript, etc.) and a build script.
+This project produces the {uri-preview}[default UI bundle] for documentation sites generated with {uri-antora}[Antora].
+It contains the UI assets (page templates, CSS, JavaScript, images, etc.) and a Gulp build script.
 The build can be used to preview the UI locally (featuring live updates), or package it for consumption by the site generator.
 
-This documentation explains how to use this project to set up, customize and manage a UI for a documentation site generated by the Antora pipeline.
+This documentation explains how to use this project to set up, customize and manage a UI for a documentation site generated with Antora.
 After reading it, you'll be able to:
 
 * [x] Understand how an Antora UI project is structured.
@@ -41,20 +35,19 @@ After reading it, you'll be able to:
 
 The Antora UI consists of the following file types that are used to structure and style the documentation site pages generated by Antora.
 
-* Handlebars "`page`" templates (layouts and partials)
+* Handlebars "`page`" templates (layouts, partials, and helpers)
 * CSS (enhanced using PostCSS)
 * JavaScript (UI scripts)
 * Images / Graphics (specific to the UI)
 * Fonts
-* HTML (sample content for previewing the UI)
-* UI model (sample data for previewing the UI)
+* Sample content for previewing the UI (HTML and UI model)
 
 To understand how the UI works, let's begin by surveying the primary technologies used by the UI.
 
 Handlebars (file extension: `.hbs`)::
 {uri-hbs}[Handlebars] is a "`logic-less`" templating engine used to create HTML from template files.
-Templates contain placeholders (i.e., mustache expressions) into which content is injected from a model.
-They also accommodate simple logic expressions for repeating content or including it conditionally.
+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_)::
 {uri-gulp}[Gulp] is a build tool for JavaScript projects.
@@ -62,7 +55,7 @@ It configures a collection of tasks that can be used to perform automated tasks
 
 Yarn (command: `yarn`)::
 {uri-yarn}[Yarn] manages software packages (i.e., software dependencies) that it downloads from {uri-npm}.
-The software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages.
+Software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages.
 (While npm itself is often used to install Yarn, we do not use npm for any other purpose).
 
 package.json:::
@@ -78,7 +71,7 @@ A local cache of resolved dependencies that Yarn (or npm) fetches.
 PostCSS::
 This project does not use a CSS preprocessor such as Sass or LESS.
 Instead, it relies on normal CSS which is enhanced by a series of postprocessors.
-The most common postprocessor backports newer CSS features to older browsers by injecting properties with vendor prefixes.
+The most common postprocessor backports newer CSS features to older browsers by adding properties with vendor prefixes.
 
 == UI project versus UI bundle
 
@@ -103,14 +96,16 @@ package.json
 yarn.lock
 src/
   css/
-    article.css
-    footer.css
+    base.css
+    breadcrumbs.css
     ...
   helpers/
     and.js
+    eq.js
     ...
   img/
-    chevron.svg
+    back.svg
+    caret.svg
     ...
   layouts/
     default.hbs
@@ -121,6 +116,7 @@ src/
     ...
   js/
     01-navigation.js
+    02-fragment-jumper.js
     ...
     vendor/
       highlight.js
@@ -145,8 +141,8 @@ A Gulp build is used to compile and assemble the UI project files into a UI bund
 
 The UI bundle--a distributable archive--provides files which are ready to be used by Antora.
 
-When the UI project files are built by Gulp, they are assembled under the [.path]_build/preview-site/../_ directory.
-Since the [.path]_build_ directory is generated, it's safe to remove.
+When the UI project files are built by Gulp, they are assembled under the [.path]_public_ directory.
+Since the [.path]_public_ directory is generated, it's safe to remove.
 
 The contents of the UI bundle resembles the UI project's master branch contents, except the bundle doesn't contain any files other than the ones that make up the UI.
 This is the content that is used by Antora.
@@ -159,9 +155,11 @@ font/
   ...
 helpers/
   and.js
+  eq.js
   ...
 img/
-  chevron.svg
+  back.svg
+  caret.svg
   ...
 layouts/
   default.hbs
@@ -179,24 +177,23 @@ js/
 Some of these files have been compiled or aggregated, such as the stylesheets and JavaScript.
 The benefit of building the UI files is that the files can be optimized for static inclusion in the site without that optimization getting in the way of UI development.
 For example, the UI build can optimize SVGs or add vendor prefixes to the CSS.
-Since this optimization is only applied to the pre-compiled files, it doesn't interfere with the web developer's workflow.
+Since these optimizations are only applied to the pre-compiled files, they don't interfere with the web developer's workflow.
 
-== UI compilation and pipeline consumption overview
+== UI compilation and generator consumption overview
 
 The purpose of an Antora UI project is to get the UI files into a state that Antora can use and to make it reusable.
 
 The UI is served statically in a production site, but the UI's assets live in a source form in a UI project to accommodate development and simplify maintenance.
-When handed off to the Antora pipeline, the UI is in an interim, pre-compiled state.
+When handed off to the Antora generator pipeline, the UI is in an interim, pre-compiled state.
 Specifically, the master branch of the git repository contains the files in source form while releases are used to distribute the files in pre-compiled form.
-// These two states (source and pre-compiled) are explained in more detail in the next two sections.
 
 The responsibility of compiling the UI is shared between a UI project and Antora.
 The UI project uses a local build to pre-compile (interpret, consolidate, and/or minimize) the files.
-The pre-compiled files are agnostic to Antora's content model, relieving the pipeline from having to deal with this part.
+The pre-compiled files are agnostic to Antora's content model, relieving the generator from having to deal with this part.
 It also allows the UI to be reused.
 
-The UI project build then packages the UI into a bundle, which Antora consumes.
-Antora grabs the bundle (which is managed by the `ui-loader` pipeline package), extracts it, and takes compilation to completion by weaving the content model into the Handlebars templates to make the pages and auxiliary data files.
+The UI project build then packages the UI into a bundle, which the UI Loader in Antora consumes.
+Antora grabs the bundle, extracts it into a UI catalog, and finally takes compilation to completion by weaving the content model into the Handlebars templates to make the pages and auxiliary data files.
 Antora then copies the remaining UI assets to the site output.
 
 Now that you have a general idea of the files that make up the UI and how it gets assembled, let's go over how to set up the project, build the UI, and preview it.
diff --git a/docs/modules/ROOT/pages/install-development-prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc
index 13df9fd..f4da144 100644
--- a/docs/modules/ROOT/pages/install-development-prerequisites.adoc
+++ b/docs/modules/ROOT/pages/prerequisites.adoc
@@ -1,11 +1,11 @@
-= Install UI Development Prerequisites
+= UI Development Prerequisites
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
-// URLs
+// URIs:
 :uri-nvm: https://github.com/creationix/nvm
 :uri-node: https://nodejs.org
 :uri-gulp: http://gulpjs.com
@@ -14,12 +14,11 @@ endif::[]
 :uri-git-dl: {uri-git}/downloads
 :uri-nvm-install: {uri-nvm}#installation
 // These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not.
-// Did we switch to Node 8 for the UI as well, or is it still 7?
 
 An Antora UI project is based on tools built atop Node.js (aka Node), namely:
 
-* {uri-nvm}[nvm] (optional, but strongly recommended)
 * {uri-node}[Node] (command: `node`)
+ ** {uri-nvm}[nvm] (optional, but strongly recommended)
 * {uri-gulp}[Gulp] (command: `gulp`)
 * {uri-yarn}[Yarn] (command: `yarn`)
 
@@ -33,21 +32,21 @@ First, make sure you have git installed.
 
 If not, {uri-git-dl}[download and install] the git package for your system.
 
-== nvm and Node 8.x
+== Node 8
 
-Next, make sure that you have Node 7.8.0 or better installed.
+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.
 
 Once you've installed nvm, open a new terminal and install the stable version of Node using the following command:
 
- $ nvm install node
+ $ nvm install 8
 
 You can switch to this version of Node at any time using the following command:
 
- $ nvm use node
+ $ nvm use 8
 
-Check the version to verify you're on Node 7.8.0 or better.
+Check the version to verify you're on Node 8 or better.
 
  $ node --version
 
diff --git a/docs/modules/ROOT/pages/set-up-existing-project.adoc b/docs/modules/ROOT/pages/set-up-project.adoc
index 2ff8ae2..b413de6 100644
--- a/docs/modules/ROOT/pages/set-up-existing-project.adoc
+++ b/docs/modules/ROOT/pages/set-up-project.adoc
@@ -1,19 +1,19 @@
-= Set Up an Existing Antora UI Project
+= Set up a UI Project
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
-// URLs
-:uri-project: https://gitlab.com/antora/antora-ui-default
+// URIs:
+:uri-project: https://gitlab.com/antora/antora-ui-default.git
 
 Before you can start working on the UI, you need to grab the sources and initialize the project.
 The sources can be {uri-project}[Antora's default UI] or an existing UI project structured to work with Antora.
 
-== Fetch a UI project
+== Fetch the Default UI project
 
-To start, clone the UI project using git:
+To start, clone the default UI project using git:
 
 [subs=attributes+]
  $ git clone {uri-project} &&
diff --git a/docs/modules/ROOT/pages/stylesheets.adoc b/docs/modules/ROOT/pages/stylesheets.adoc
index 5b1e682..7745b35 100644
--- a/docs/modules/ROOT/pages/stylesheets.adoc
+++ b/docs/modules/ROOT/pages/stylesheets.adoc
@@ -2,7 +2,7 @@
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
 
@@ -21,7 +21,7 @@ The modifications mostly center around injecting vendor prefixes for compatibili
 Let's consider the case when you want to modify the font size of a section title.
 
 First, make sure you have set up the project and created a development branch.
-Next, open the file [.path]_stylesheets/article.css_ and modify the rule for the section title.
+Next, open the file [.path]_src/css/doc.css_ and modify the rule for the section title.
 
 [source,css]
 ----
diff --git a/docs/modules/ROOT/pages/templates.adoc b/docs/modules/ROOT/pages/templates.adoc
index 1df9521..da823db 100644
--- a/docs/modules/ROOT/pages/templates.adoc
+++ b/docs/modules/ROOT/pages/templates.adoc
@@ -2,7 +2,7 @@
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
 
@@ -15,70 +15,108 @@ The layout templates, which are stored in [.path]_src/layouts/_, provide the mai
 The partial templates, in [.path]_src/partials/_, fill in different regions of a page, such as the navigation and footer.
 
 The templates read from a model that's populated by Antora.
-Places in the template where the model is read are enclosed in `{{` and `}}` markers, aka mustaches (e.g., `+{{title}}+`).
+Places in the template where the model is read are enclosed in `{{` and `}}` markers or `{{{` and `}}}`, aka mustaches (e.g., `+{{{page.title}}}+`).
+Double mustaches escape the content, whereas triple mustaches insert the content verbatim.
 When the `{{` is immediately followed by `>`, that's where the result of a partial is inserted (e.g., `+{{> head }}+`.
 
 === Template variables
 
-*This model is not final.*
-*Variable names and purposes may change.*
+CAUTION: This model is not final.
+Variable names and purposes may change.
 
-Here's an overview of the available model:
+Here's an overview of the available UI model:
 
 .Variables available to the Handlebars templates
-[#template-variables,cols="1m,3"]
+[#template-variables-table,cols="1m,3"]
 |===
 | Name | Description
 
 | site
 | Information about the site.
-Properties include url, title, buildNumber, domains, aspect, aspectNav, and swiftypeKey.
 
-| title
+| site.url
+| The base URL of the site, if specified.
+
+| site.title
+| The title of the site.
+
+| site.components
+| A collection of all the components in the site.
+
+| site.ui
+| Information about the site UI.
+
+| site.ui.defaultLayout
+| The default page layout used for this site.
+
+| site.ui.url
+| The absolute base URL of the UI.
+
+| page
+| Information about the current page.
+
+| page.title
 | The page title (also used as the primary heading).
 
-| contents
+| page.contents
 | The main article content in HTML format.
 Sourced from AsciiDoc and converted to HTML by the Asciidoctor processor.
 
-| description
+| page.attributes
+| AsciiDoc header attributes that are prefixed with `page-`.
+The `page-` prefix is dropped from these names.
+
+| page.description
 | The text of the description attribute in the AsciiDoc header, if specified.
 
-| keywords
+| page.keywords
 | A comma-separated list of keywords defined in the AsciiDoc header, if specified.
 
-| domain
-| Information about the navigation domain of the current page.
-Properties include name, title, type, versioned, version, versions, url, root, and siteAspect.
+| page.component
+| Information about the component for the current page.
+Properties include name, title, and versions.
+
+| page.componentVersion
+| Information about the component version for the current page.
+Properties include name, title, and url.
+
+| page.module
+| The name of the module for the current page.
 
-| versions
+| page.version
+| The name of the version for the current page.
+
+| page.versions
 | All versions of the current page, including the current page.
 Each entry has the properties url, string, and missing.
 
-| breadcrumbs
+| page.breadcrumbs
 | An array of breadcrumb items that represent the current selection in the navigation tree.
 
-| uiRootPath
-| The path to the root directory of the UI.
+| page.navigation
+| A collection of navigation links for the current page.
+Each navigation item contains the property `content` as well as the optional properties `url` and (child) `items`.
 
-| canonicalUrl
+| page.canonicalUrl
 | The canonical URL for the current page.
 If there are older versions of the page, the canonical URL is the URL of the latest version.
 If this is an aspect page, the canonical URL is the URL of the primary (non-aspect) page.
 
-| editUrl
+| page.editUrl
 | The URL to edit the current page, typically on GitHub.
 
-| siteRootUrl
-| The URL of the site root relative to the current page.
-If the site does not have a root component, this value is null.
-
-| home
+| page.home
 | Indicates whether the current page is the home page of the site.
 
-| navigation
-| A collection of navigation links for the current page.
-Each navigation item contains the property `text` as well as the optional properties `href` and (child) `items`.
+| page.layout
+| The page layout for the current page.
+
+| uiRootPath
+| The path to the root directory of the UI.
+
+//| siteRootUrl
+//| The URL of the site root relative to the current page.
+//If the site does not have a root component, this value is null.
 |===
 
 This model is likely to grow over time.
@@ -92,10 +130,10 @@ Next, open the file [.path]_templates/partials/head.hbs_ and add your tag.
 
 [source,html]
 ----
-<meta class="swiftype" name="title" data-type="string" content="{{title}}">
+<meta class="swiftype" name="title" data-type="string" content="{{page.title}}">
 ----
 
 Each template file has access to the template model, which exposes information about the current page through variable names.
-The variables currently available are listed in <<template-variables>>.
+The variables currently available are listed in <<template-variables-table>>.
 
 Save the file, commit it to git, push the branch, and allow the approval workflow to play out.