revise documentation for accuracy
authorDan Allen <dan@opendevise.com>
Wed, 10 Jan 2018 09:23:40 +0000 (02:23 -0700)
committerDan Allen <dan@opendevise.com>
Wed, 10 Jan 2018 09:24:26 +0000 (02:24 -0700)
12 files changed:
docs/antora.yml
docs/modules/ROOT/nav.adoc
docs/modules/ROOT/pages/build-local-project.adoc [deleted file]
docs/modules/ROOT/pages/build-preview-ui.adoc [new file with mode: 0644]
docs/modules/ROOT/pages/development-workflow.adoc
docs/modules/ROOT/pages/index.adoc
docs/modules/ROOT/pages/install-development-prerequisites.adoc [deleted file]
docs/modules/ROOT/pages/prerequisites.adoc [new file with mode: 0644]
docs/modules/ROOT/pages/set-up-existing-project.adoc [deleted file]
docs/modules/ROOT/pages/set-up-project.adoc [new file with mode: 0644]
docs/modules/ROOT/pages/stylesheets.adoc
docs/modules/ROOT/pages/templates.adoc

index aa929d2..1807fb2 100644 (file)
@@ -1,5 +1,5 @@
 name: antora-ui-default
-title: Antora UI
+title: Antora Default UI
 version: master
 nav:
 - modules/ROOT/nav.adoc
index 5d0b702..1c72071 100644 (file)
@@ -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-local-project.adoc
deleted file mode 100644 (file)
index 558794b..0000000
+++ /dev/null
@@ -1,69 +0,0 @@
-= 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/build-preview-ui.adoc b/docs/modules/ROOT/pages/build-preview-ui.adoc
new file mode 100644 (file)
index 0000000..cc44296
--- /dev/null
@@ -0,0 +1,70 @@
+= Build a UI Project for Local Preview
+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-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).
+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]_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.
+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 `--ui-bundle` command-line option.
index 2d9b787..9ce6fc0 100644 (file)
@@ -2,7 +2,7 @@
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
-// Settings
+// Settings:
 :idprefix:
 :idseparator: -
 
index cf6794d..359fc24 100644 (file)
@@ -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/install-development-prerequisites.adoc
deleted file mode 100644 (file)
index 13df9fd..0000000
+++ /dev/null
@@ -1,74 +0,0 @@
-= 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/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc
new file mode 100644 (file)
index 0000000..f4da144
--- /dev/null
@@ -0,0 +1,73 @@
+= UI Development Prerequisites
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings:
+: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
+// 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`)
+
+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.
+
+== Node 8
+
+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 8
+
+You can switch to this version of Node at any time using the following command:
+
+ $ nvm use 8
+
+Check the version to verify you're on Node 8 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
deleted file mode 100644 (file)
index 2ff8ae2..0000000
+++ /dev/null
@@ -1,67 +0,0 @@
-= 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/set-up-project.adoc b/docs/modules/ROOT/pages/set-up-project.adoc
new file mode 100644 (file)
index 0000000..b413de6
--- /dev/null
@@ -0,0 +1,67 @@
+= Set up a UI Project
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings:
+:idprefix:
+:idseparator: -
+// 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 the Default UI project
+
+To start, clone the default 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.
index 5b1e682..7745b35 100644 (file)
@@ -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]
 ----
index 1df9521..da823db 100644 (file)
@@ -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.