You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
NOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present.
49
56
This setting is required because updates to the UI bundle are pushed to the same URL.
50
57
If the URL were to be unique, this setting would not be required.
51
58
52
-
Read on to learn how to customize the default UI for your own documentation.
53
-
54
-
== Development Quickstart
59
+
=== Development Quick(ish)start
55
60
56
-
This section offers a basic tutorial to teach you how to set up the default UI project, preview it locally, and bundle it for use with Antora.
61
+
Here is how to set up the UI projectand preview it locally.
57
62
A more comprehensive tutorial can be found in the documentation at {url-antora-docs}.
58
63
59
-
=== Prerequisites
64
+
==== Prerequisites
60
65
61
-
To preview and bundle the default UI, you need the following software on your computer:
66
+
To preview and bundle the UI theme, you need the following software on your computer:
62
67
63
-
* {url-git}[git] (command: `git`)
64
68
* {url-nodejs}[Node.js] (commands: `node` and `npm`)
65
69
* {url-gulp}[Gulp CLI] (command: `gulp`)
66
70
67
-
==== git
68
-
69
-
First, make sure you have git installed.
70
-
71
-
$ git --version
72
71
73
-
If not, {url-git-dl}[download and install] the git package for your system.
72
+
===== Node.js
74
73
75
-
==== Node.js
76
-
77
-
Next, make sure that you have Node.js installed (which also provides npm).
74
+
Make sure that you have Node.js installed (which also provides npm).
78
75
79
76
$ node --version
80
77
81
78
If this command fails with an error, you don't have Node.js installed.
82
79
If the command doesn't report an LTS version of Node.js (e.g., v10.15.3), it means you don't have a suitable version of Node.js installed.
83
-
In this guide, we'll be installing Node.js 10.
80
+
In this guide, we'll be installing Node.js 16.
84
81
85
82
While you can install Node.js from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to manage your Node.js installation(s).
86
83
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.
87
84
88
-
Once you've installed nvm, open a new terminal and install Node.js 10 using the following command:
85
+
Once you've installed nvm, open a new terminal and install Node.js 16 using the following command:
89
86
90
-
$ nvm install 10
87
+
$ nvm install 16
91
88
92
89
You can switch to this version of Node.js at any time using the following command:
93
90
94
-
$ nvm use 10
95
-
96
-
To make Node.js 10 the default in new terminals, type:
91
+
$ nvm use 16
97
92
98
-
$ nvm alias default 10
99
93
100
94
Now that you have Node.js installed, you can proceed with installing the Gulp CLI.
101
95
102
-
==== Gulp CLI
96
+
===== Gulp CLI
103
97
104
98
You'll need the Gulp command-line interface (CLI) to run the build.
105
99
The Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.
@@ -122,16 +116,7 @@ Alternately, you can use the `gulp` command that is installed by the project's d
122
116
123
117
Now that you have the prerequisites installed, you can fetch and build the UI project.
124
118
125
-
=== Clone and Initialize the UI Project
126
-
127
-
Clone the default UI project using git:
128
-
129
-
[subs=attributes+]
130
-
$ git clone {url-project} &&
131
-
cd "`basename $_`"
132
-
133
-
The example above clones Antora's default UI project and then switches to the project folder on your filesystem.
134
-
Stay in this project folder when executing all subsequent commands.
119
+
==== Initialize the UI Project
135
120
136
121
Use npm to install the project's dependencies inside the project.
137
122
In your terminal, execute the following command:
@@ -148,9 +133,9 @@ If you prefer to install packages using Yarn, run this command instead:
148
133
$ yarn
149
134
====
150
135
151
-
=== Preview the UI
136
+
==== Preview the UI
152
137
153
-
The default UI project is configured to preview offline.
138
+
The UI project is set up to preview offline.
154
139
The files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action.
155
140
In this folder, you'll primarily find pages written in AsciiDoc.
156
141
These pages provide a representative sample and kitchen sink of content from the real site.
@@ -174,10 +159,16 @@ This works by monitoring the project for changes, running the `preview:build` ta
174
159
175
160
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
176
161
177
-
=== Package for Use with Antora
162
+
==== Package for Use with Antora
163
+
164
+
[WARNING]
165
+
This should not normally be necessary. The usual way to package and deploy this site is by
166
+
running a CI build. However, it is occasionally useful to bundle it in order to
167
+
try out changes on the full site by using the `--ui-bundle-url` command-line option.
178
168
179
169
If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
180
170
171
+
181
172
$ gulp bundle
182
173
183
174
If any errors are reported by lint, you'll need to fix them.
@@ -191,7 +182,7 @@ If you have the preview running, and you want to bundle without causing the prev
191
182
192
183
The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
193
184
194
-
==== Source Maps
185
+
===== Source Maps
195
186
196
187
The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
197
188
{url-source-maps}[Source maps] correlate these combined files with their original sources.
@@ -214,6 +205,3 @@ Copyright (C) 2017-present OpenDevise Inc. and the Antora Project.
214
205
Use of this software is granted under the terms of the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License Version 2.0] (MPL-2.0).
215
206
See link:LICENSE[] to find the full license text.
216
207
217
-
== Authors
218
-
219
-
Development of Antora is led and sponsored by {url-opendevise}[OpenDevise Inc].
0 commit comments