1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
= Antora Default UI
// Settings:
:idprefix:
:idseparator: -
:experimental:
:hide-uri-scheme:
// URIs:
: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
: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 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 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:
* [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, partials, and helpers)
* CSS (enhanced using PostCSS)
* JavaScript (UI scripts)
* Images / Graphics (specific to the UI)
* Fonts
* 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 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/index.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}.
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 adding 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/
index.js
...
package.json
yarn.lock
src/
css/
base.css
breadcrumbs.css
...
helpers/
and.js
eq.js
...
img/
back.svg
caret.svg
...
layouts/
default.hbs
404.hbs
partials/
article.hbs
breadcrumbs.hbs
...
js/
01-navigation.js
02-fragment-jumper.js
...
vendor/
highlight.js
preview-site-src/
index.html
ui-model.yml
....
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]_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.
[.output]
....
css/
site.css
font/
...
helpers/
and.js
eq.js
...
img/
back.svg
caret.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 these optimizations are only applied to the pre-compiled files, they don't interfere with the web developer's workflow.
== 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.
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 (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 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 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.
|
