add ui development documentation

- set up documentation component for Antora
- add rough page order to nav.adoc
- minor typo fix to README

8 files changed, 587 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc
new file mode 100644
index 0000000..fb98244
--- /dev/null
+++ b/docs/modules/ROOT/pages/_attributes.adoc
@@ -0,0 +1,2 @@
+:moduledir: ..
+include::{moduledir}/_attributes.adoc[]
diff --git a/docs/modules/ROOT/pages/build-local-project.adoc b/docs/modules/ROOT/pages/build-local-project.adoc
new file mode 100644
index 0000000..558794b
--- /dev/null
+++ b/docs/modules/ROOT/pages/build-local-project.adoc
@@ -0,0 +1,69 @@
+= Build a UI Project for Local Previewing
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+:experimental:
+
+== 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).
+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).
+Thus, to look at then, you need to run them through the UI build.
+
+There are two preview modes available.
+You can run the build once and examine the result or you can run the build continuously so you can see changes as you make them.
+The next two sections explain how to use these modes.
+
+=== Build Once
+
+To build the UI once for preview, then stop, execute the `build-preview` task using the following command:
+
+ $ 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_).
+
+=== 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.
+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:
+
+....
+[BS] Access URLs:
+ ----------------------------------
+    Local: http://localhost:5252
+ External: http://192.168.1.7:5252
+ ----------------------------------
+[BS] Serving files from: build
+[BS] Watching files...
+....
+
+Navigate to the first one to see 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.
+
+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:
+
+ $ gulp pack
+
+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.
diff --git a/docs/modules/ROOT/pages/development-workflow.adoc b/docs/modules/ROOT/pages/development-workflow.adoc
new file mode 100644
index 0000000..2d9b787
--- /dev/null
+++ b/docs/modules/ROOT/pages/development-workflow.adoc
@@ -0,0 +1,37 @@
+= UI Development Workflow
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+// This section provides information about some of the UI files you'll be modifying and how to prepare and submit those changes.
+
+All changes pushed to a UI project's master branch can trigger a new release (not described here).
+Therefore, you want to make your changes to a development branch and submit it as a pull request (PR) to be approved.
+(Even better would be to issue the PR from a fork).
+Only when the PR is approved and merged will the new release be triggered.
+
+== git steps
+
+Use the following command to create a local development branch named `name-me`:
+
+ $ git checkout -b name-me -t origin/master
+
+You'll then apply your changes to the UI files.
+Once you're done making changes, commit those changes to the local branch:
+
+ $ git commit -a -m "describe your change"
+
+Then, push your branch to the remote repository:
+
+ $ git push origin name-me
+
+Finally, navigate to your UI project in your browser and create a new pull request from this branch.
+
+The maintainer of the UI should review the changes.
+If the changes are acceptable, the maintainer will merge the pull request.
+As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.
+
+Now that you've got the process down, let's review some of the files you'll be working with in more detail.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000..cf6794d
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,202 @@
+= 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-preview: https://antora.gitlab.io/antora-ui-default
+:uri-hbs: http://handlebarsjs.com
+:uri-gulp: http://gulpjs.com
+:uri-yarn: https://yarnpkg.com
+:uri-npm: https://npmjs.com
+:uri-node: https://nodejs.org
+:uri-nvm: https://github.com/creationix/nvm
+:uri-nvm-install: {uri-nvm}#installation
+: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.
+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.
+After reading it, you'll be able to:
+
+* [x] Understand how an Antora UI project is structured.
+* [x] Set up your environment to work on the UI project.
+* [x] Launch a preview server to visually inspect the UI.
+* [x] Adopt a development workflow to share and accept changes to the UI.
+* [x] Package a UI for your documentation site that Antora can use.
+
+== File type and technology overview
+
+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)
+* 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)
+
+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.
+
+Gulp (script file: [.path]_gulpfile.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.
+
+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.
+(While npm itself is often used to install Yarn, we do not use npm for any other purpose).
+
+package.json:::
+This file keeps track of the dependencies (described using fuzzy versions) that Yarn should fetch.
+
+yarn.lock:::
+This file contains a report of which dependencies Yarn resolved.
+This information ensures that the dependency resolution is reproducible.
+
+node_modules/:::
+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.
+
+== UI project versus UI bundle
+
+The [.term]*UI project*, the master branch of a git repository, contains the recipe and raw materials for creating an Antora UI bundle.
+It includes a build, source files, project files, and dependency information.
+This is your development workspace.
+
+The [.term]*UI bundle*, a distributable archive, provides pre-compiled (interpreted, consolidated, and/or minimized) files that are ready to be used by Antora.
+
+=== UI project repository structure (master branch)
+
+You should think of the UI project's master branch as your UI workspace.
+It contains the recipe and raw materials for creating a UI, including a build, source files, project files, and dependency information.
+
+Here's how the files are structured in the UI project:
+
+[.output]
+....
+README.adoc
+gulpfile.js
+package.json
+yarn.lock
+src/
+  css/
+    article.css
+    footer.css
+    ...
+  helpers/
+    and.js
+    ...
+  img/
+    chevron.svg
+    ...
+  layouts/
+    default.hbs
+    404.hbs
+  partials/
+    article.hbs
+    breadcrumbs.hbs
+    ...
+  js/
+    01-navigation.js
+    ...
+    vendor/
+      highlight.js
+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.
+
+=== UI bundle structure (releases)
+
+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.
+
+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.
+
+[.output]
+....
+css/
+  site.css
+font/
+  ...
+helpers/
+  and.js
+  ...
+img/
+  chevron.svg
+  ...
+layouts/
+  default.hbs
+  404.hbs
+partials/
+  article.hbs
+  breadcrumbs.hbs
+  ...
+js/
+  site.js
+  vendor/
+    highlight.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.
+
+== UI compilation and pipeline 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.
+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.
+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.
+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/install-development-prerequisites.adoc
new file mode 100644
index 0000000..13df9fd
--- /dev/null
+++ b/docs/modules/ROOT/pages/install-development-prerequisites.adoc
@@ -0,0 +1,74 @@
+= Install UI Development Prerequisites
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+// URLs
+: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
+// 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-gulp}[Gulp] (command: `gulp`)
+* {uri-yarn}[Yarn] (command: `yarn`)
+
+You also need {uri-git}[git] (command: `git`) to pull down the project and push updates to it.
+
+== git
+
+First, make sure you have git installed.
+
+ $ git --version
+
+If not, {uri-git-dl}[download and install] the git package for your system.
+
+== nvm and Node 8.x
+
+Next, make sure that you have Node 7.8.0 or better 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
+
+You can switch to this version of Node at any time using the following command:
+
+ $ nvm use node
+
+Check the version to verify you're on Node 7.8.0 or better.
+
+ $ node --version
+
+== Gulp CLI
+
+Next, you'll need the Gulp CLI (aka wrapper).
+This package provides the `gulp` command which 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:
+
+ $ npm install -g gulp-cli
+
+== Yarn
+
+Finally, you will need Yarn, which is the preferred package manager for the Node ecosystem.
+You'll need to use the `npm` command to install Yarn, though this is the last time you'll use the `npm` command.
+You should install Yarn globally (which resolves to a location in your user directory if you're using nvm) using the following command:
+
+ $ npm install -g yarn
+
+Verify Yarn is installed by checking the version:
+
+ $ yarn --version
+
+Now that you have Node, Yarn, and Gulp installed, you're ready to set up the project.
diff --git a/docs/modules/ROOT/pages/set-up-existing-project.adoc b/docs/modules/ROOT/pages/set-up-existing-project.adoc
new file mode 100644
index 0000000..2ff8ae2
--- /dev/null
+++ b/docs/modules/ROOT/pages/set-up-existing-project.adoc
@@ -0,0 +1,67 @@
+= Set Up an Existing Antora UI Project
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+// URLs
+:uri-project: https://gitlab.com/antora/antora-ui-default
+
+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
+
+To start, clone the UI project using git:
+
+[subs=attributes+]
+ $ git clone {uri-project} &&
+   cd "`basename $_`"
+
+The example above clones Antora's default UI project and then switches to the project folder on your filesystem.
+Stay in this project folder in order to initialize the project using Yarn.
+
+== Install dependencies
+
+Next, you'll need to initialize the project.
+Initializing the project essentially means downloading and installing the dependencies into the project.
+That's the job of Yarn.
+
+In your terminal, execute the following command (while inside the project folder):
+
+ $ yarn install
+
+This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.
+This folder does not get included in the UI bundle.
+The folder is safe to delete, though Yarn does a great job of managing it.
+
+You'll notice another file which seems to be relevant here, [.path]_yarn.lock_.
+Yarn uses this file to determine which specific version of a dependency to use, since versions in [.path]_package.json_ are typically just a range.
+The information in this file makes the build reproducible across different machines and runs.
+
+If a new dependency must be resolved that isn't yet listed in [.path]_yarn.lock_, Yarn will update this file with the new information when you run `yarn install`.
+Therefore, you're advised to commit this file into the repository whenever it changes.
+
+== Supported build tasks
+
+Now that the dependencies are installed, you should be able to run the `gulp` command to find out what tasks the build supports:
+
+ $ gulp --tasks-simple
+
+You should see:
+
+[.output]
+....
+lint:css
+lint:js
+lint
+format
+build
+build:preview
+preview
+pack
+default
+....
+
+We'll explain what each of these tasks are for and when to use them.
diff --git a/docs/modules/ROOT/pages/stylesheets.adoc b/docs/modules/ROOT/pages/stylesheets.adoc
new file mode 100644
index 0000000..5b1e682
--- /dev/null
+++ b/docs/modules/ROOT/pages/stylesheets.adoc
@@ -0,0 +1,35 @@
+= Work with the CSS Stylesheets
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+The stylesheets are written in CSS.
+These stylesheets utilize CSS variables to keep the CSS DRY and easy to customize.
+
+== Stylesheet organization and processing
+
+Within the default UI project, the stylesheet files are separated into modules to help organize the rules and make them easier to find.
+The UI build combines and minifies these files into a single file named [.path]_site.css_.
+During the build, the CSS is enhanced using PostCSS in much the same way as a CSS preprocessor works, only the modifications are made to the CSS directly.
+The modifications mostly center around injecting vendor prefixes for compatibility or backporting new features to more broadly supported syntax.
+
+== Add a new CSS rule
+
+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.
+
+[source,css]
+----
+.doc h1 {
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+  margin-top: 2rem
+}
+----
+
+Save the file, commit it to git, push the branch, and allow the approval workflow to play out.
diff --git a/docs/modules/ROOT/pages/templates.adoc b/docs/modules/ROOT/pages/templates.adoc
new file mode 100644
index 0000000..1df9521
--- /dev/null
+++ b/docs/modules/ROOT/pages/templates.adoc
@@ -0,0 +1,101 @@
+= Work with the Handlebars Templates
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+Antora combines the Handlebars templates with the converted AsciiDoc content to make the pages in the site.
+These "`logic-less`" templates are mostly HTML with some special mustache tags sprinkled in where content is to be inserted.
+
+== What do the templates do?
+
+The layout templates, which are stored in [.path]_src/layouts/_, provide the main page structure.
+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}}+`).
+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.*
+
+Here's an overview of the available model:
+
+.Variables available to the Handlebars templates
+[#template-variables,cols="1m,3"]
+|===
+| Name | Description
+
+| site
+| Information about the site.
+Properties include url, title, buildNumber, domains, aspect, aspectNav, and swiftypeKey.
+
+| title
+| The page title (also used as the primary heading).
+
+| contents
+| The main article content in HTML format.
+Sourced from AsciiDoc and converted to HTML by the Asciidoctor processor.
+
+| description
+| The text of the description attribute in the AsciiDoc header, if specified.
+
+| 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.
+
+| versions
+| All versions of the current page, including the current page.
+Each entry has the properties url, string, and missing.
+
+| 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.
+
+| 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
+| 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
+| 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`.
+|===
+
+This model is likely to grow over time.
+
+== Modify a template
+
+Let's consider the case when you want to add a new meta tag inside the HTML head.
+
+First, make sure you have set up the project and created a development branch.
+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}}">
+----
+
+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>>.
+
+Save the file, commit it to git, push the branch, and allow the approval workflow to play out.