blob: b413de6517e30c2919dd8ffe981fbf9bbd19bb61 (
plain)
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
|
= 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.
|
