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+]
----
==== 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:
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:
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
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.
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:
* 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]
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:
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.
== 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:
projects / working / eg-antora.git / commitdiff