61 lines
2.1 KiB
Plaintext
61 lines
2.1 KiB
Plaintext
= Set up a UI Project
|
|
:url-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 {url-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 {url-project}
|
|
$ cd "`basename ${_%.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 npm.
|
|
|
|
== 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 npm.
|
|
|
|
In your terminal, execute the following command (while inside the project folder):
|
|
|
|
$ npm 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 npm does a great job of managing it.
|
|
|
|
You'll notice another file which seems to be relevant here, [.path]_package-lock.json_.
|
|
npm uses this file to determine which concrete 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]_package-lock.json_, npm will update this file with the new information when you run `npm install`.
|
|
Therefore, you're advised to commit the [.path]_package-lock.json_ 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]
|
|
....
|
|
default
|
|
clean
|
|
lint
|
|
format
|
|
build
|
|
bundle
|
|
bundle:pack
|
|
preview
|
|
preview:build
|
|
....
|
|
|
|
We'll explain what each of these tasks are for and when to use them.
|