add ui development documentation

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

1 files changed, 202 insertions, 0 deletions

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.