diff options
| -rw-r--r-- | README.adoc | 16 | ||||
| -rw-r--r-- | docs/modules/ROOT/nav.adoc | 4 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/index.adoc | 10 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/prerequisites.adoc | 2 |
4 files changed, 16 insertions, 16 deletions
diff --git a/README.adoc b/README.adoc index 16e1d7e..8133049 100644 --- a/README.adoc +++ b/README.adoc @@ -21,11 +21,11 @@ image:{img-ci-status}[CI Status (GitLab CI), link={uri-ci-pipelines}] This project is an archetype that demonstrates how to produce a UI bundle for use in a documentation site generated with {uri-antora}[Antora]. -You can see a preview the default UI at {uri-preview}. +You can see a preview of the default UI at {uri-preview}. -== Using the Default UI +== Use the Default UI -If you want to use the default UI for your Antora-based site, add the following UI configuration to your playbook: +If you want to use the default UI for your Antora-generated site, add the following UI configuration to your playbook: [source,yaml,subs=attributes+] ---- @@ -94,7 +94,7 @@ You should install the Gulp CLI globally (which resolves to a location in your u ==== Yarn -Finally, you will need Yarn, which is the preferred package manager for the Node ecosystem. +Finally, you'll need Yarn, which is the preferred package manager for the Node ecosystem. You should install Yarn globally (which resolves to a location in your user directory if you're using nvm) using the following command: @@ -102,7 +102,7 @@ You should install Yarn globally (which resolves to a location in your user dire Now that you have the prerequisites installed, you can fetch and build the default UI project. -=== Cloning and Initializing the Project +=== Clone and Initialize the UI Project Clone the default UI project using git: @@ -113,7 +113,7 @@ Clone the default UI project using git: 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. -You'll use Yarn to install the project's dependencies. +Use Yarn to install the project's dependencies. In your terminal, execute the following command (while inside the project folder): $ yarn install @@ -121,7 +121,7 @@ In your terminal, execute the following command (while inside the project folder 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. -=== Previewing the UI +=== Preview the UI The default UI project is configured to preview offline. That's what the files in the [.path]_preview-site-src/_ folder are for. @@ -150,7 +150,7 @@ This works by monitoring the project for changes, running the `build` task if a Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. -=== Packaging for Use with Antora +=== 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: diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 1c72071..543cbd5 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,6 +2,6 @@ * 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:development-workflow.adoc[UI Development Workflow] +* xref:templates.adoc[Work with the Handlebars Templates] +* xref:stylesheets.adoc[Work with the CSS Stylesheets] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 359fc24..f4a227e 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -20,7 +20,7 @@ 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. +The build can be used to preview the UI locally (featuring live updates), or to package it for consumption by the Antora site generator. 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: @@ -184,16 +184,16 @@ Since these optimizations are only applied to the pre-compiled files, they don't 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 generator pipeline, the UI is in an interim, pre-compiled state. +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. 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 UI project uses a local build to pre-compile (i.e., interpret, consolidate, and/or minimize) the files. 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 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 grabs the bundle, extracts it into a UI catalog, and takes compilation to completion by weaving the Antora's 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. +Now that you have an overview 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/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc index d0fda9a..28a0f7b 100644 --- a/docs/modules/ROOT/pages/prerequisites.adoc +++ b/docs/modules/ROOT/pages/prerequisites.adoc @@ -62,7 +62,7 @@ You should install the Gulp CLI globally (which resolves to a location in your u == Yarn -Finally, you will need Yarn, which is the preferred package manager for the Node ecosystem. +Finally, you'll 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: |