To preview and bundle the default UI, you need the following software on your computer:
* {uri-git}[git] (command: `git`)
-* {uri-node}[Node 8] (command: `node`)
+* {uri-node}[Node] (command: `node`)
* {uri-gulp}[Gulp CLI] (command: `gulp`)
* {uri-yarn}[Yarn] (command: `yarn`)
If not, {uri-git-dl}[download and install] the git package for your system.
-==== Node 8
+==== Node
-Next, make sure that you have Node 8 installed.
+Next, make sure that you have Node.js (herein "`Node`") installed.
$ node --version
If this command fails with an error, you don't have Node installed.
-If the command doesn't report a Node 8 version (e.g., v8.9.4), you don't have a suitable version of Node installed.
+If the command doesn't report a Node LTS version (e.g., v10.14.2), you don't have a suitable version of Node installed.
While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node.
Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
-Once you've installed nvm, open a new terminal and install Node 8 using the following command:
+Once you've installed nvm, open a new terminal and install Node 10 using the following command:
- $ nvm install 8
+ $ nvm install 10
You can switch to this version of Node at any time using the following command:
- $ nvm use 8
+ $ nvm use 10
-To make Node 8 the default in new terminals, type:
+To make Node 10 the default in new terminals, type:
- $ nvm alias default 8
+ $ nvm alias default 10
-Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn.
+Now that you have Node 10 installed, you can proceed with installing the Gulp CLI and Yarn.
==== Gulp CLI
$ gulp preview
-You'll see two URLs listed in the output of this command:
+You'll see a URL listed in the output of this command:
....
-[BS] Access URLs:
- ----------------------------------
- Local: http://localhost:5252
- External: http://192.168.1.7:5252
- ----------------------------------
-[BS] Serving files from: build
-[BS] Watching files...
+[12:59:28] Starting 'preview:serve'...
+[12:59:28] Starting server...
+[12:59:28] Server started http://localhost:5252
+[12:59:28] Running server
....
-Navigate to the first URL to see the preview site.
+Navigate to that URL to view the preview site.
While this command is running, any changes you make to the source files will be instantly reflected in the browser.
-This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser.
+This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
=== 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:
+If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
- $ gulp pack
+ $ gulp bundle
The UI bundle will be available at [.path]_build/ui-bundle.zip_.
-You can then point Antora at this bundle using the `--ui-bundle` command-line option.
+You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
== Copyright and License
To build the UI once for preview, then stop, execute the `build-preview` task using the following command:
- $ gulp build:preview
+ $ gulp preview:build
This task pre-compiles the UI files into the [.path]_public_ directory.
To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_).
=== Build Continuously
-To avoid the need to run the `build-preview` task over and over, you can use the `preview` command instead to have it run continuously.
+To avoid the need to run the `preview:build` task over and over, you can use the `preview` command instead to have it run continuously.
This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`").
To launch the preview server, execute the following command:
$ gulp preview
-You'll see two URLs listed in the output of this command:
+You'll see a URL listed in the output of this command:
....
-[BS] Access URLs:
- ----------------------------------
- Local: http://localhost:5252
- External: http://192.168.1.7:5252
- ----------------------------------
-[BS] Serving files from: build
-[BS] Watching files...
+[12:59:28] Starting 'preview:serve'...
+[12:59:28] Starting server...
+[12:59:28] Server started http://localhost:5252
+[12:59:28] Running server
....
-Navigate to the first one to see the preview site.
+Navigate to the URL to view the preview site.
While this command is running, any changes you make to the source files will be instantly reflected in the browser.
-This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser.
+This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
== Package for Previewing
-If you need to package the UI in order to preview the UI on the real site in local development, run the following command:
+If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
- $ gulp pack
+ $ gulp bundle
-The `pack` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
+The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
The UI bundle will be available at [.path]_build/ui-bundle.zip_.
You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
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_)::
+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.
[.output]
....
README.adoc
-gulpfile.js
+gulpfile.js/
+ index.js
+ ...
package.json
yarn.lock
src/
preview-site-src/
index.html
ui-model.yml
-tasks/
- lib/
- gulp-prettier-eslint.js
- build.js
- build-preview.js
- format.js
- lint-css.js
- lint-js.js
- pack.js
- preview.js
....
A Gulp build is used to compile and assemble the UI project files into a UI bundle.
:idprefix:
:idseparator: -
// URIs:
-:uri-nvm: https://github.com/creationix/nvm
-:uri-node: https://nodejs.org
-:uri-gulp: http://gulpjs.com
-:uri-yarn: https://yarnpkg.com
-:uri-git: https://git-scm.com
-:uri-git-dl: {uri-git}/downloads
-:uri-nvm-install: {uri-nvm}#installation
+:url-nvm: https://github.com/creationix/nvm
+:url-node: https://nodejs.org
+:url-gulp: http://gulpjs.com
+:url-yarn: https://yarnpkg.com
+:url-git: https://git-scm.com
+:url-git-dl: {url-git}/downloads
+:url-node-releases: https://nodejs.org/en/about/releases/
// These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not.
An Antora UI project is based on tools built atop Node.js (aka Node), namely:
-* {uri-node}[Node] (command: `node`)
- ** {uri-nvm}[nvm] (optional, but strongly recommended)
-* {uri-gulp}[Gulp] (command: `gulp`)
-* {uri-yarn}[Yarn] (command: `yarn`)
+* {url-node}[Node] (command: `node`)
+ ** {url-nvm}[nvm] (optional, but strongly recommended)
+* {url-gulp}[Gulp] (command: `gulp`)
+* {url-yarn}[Yarn] (command: `yarn`)
-You also need {uri-git}[git] (command: `git`) to pull down the project and push updates to it.
+You also need {url-git}[git] (command: `git`) to pull down the project and push updates to it.
== git
$ git --version
-If not, {uri-git-dl}[download and install] the git package for your system.
+If not, {url-git-dl}[download and install] the git package for your system.
-== Node 8
+== Node
-Next, make sure that you have Node 8 installed.
-While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node.
-Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
+You need Node installed on your machine to use Antora, including the default UI.
+Antora follows Node's release schedule, so we advise that you choose an active long term support (LTS) release of Node.
+We recommend using the latest active Node LTS version.
+While you can use other versions of Node, Antora is only tested against LTS releases.
-Once you've installed nvm, open a new terminal and install Node 8 using the following command:
+To check whether you have Node installed, and which version, open a terminal and type:
- $ nvm install 8
+ $ node --version
-You can switch to this version of Node at any time using the following command:
+You should see a version string, such as:
- $ nvm use 8
+ v10.14.2
-To make Node 8 the default in new terminals, type:
+If the command fails with an error, it means you don't have Node installed.
+The best way to install Node is to use nvm (Node Version Manager).
+Refer to xref:antora:install:linux-requirements.adoc#install-nvm[Install nvm and Node (Linux)], xref:antora:install:macos-requirements.adoc#install-nvm[Install nvm and Node (macOS)], or xref:antora:install:windows-requirements.adoc#install-nvm[Install nvm and Node (Windows)] for instructions.
- $ nvm alias default 8
-
-Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn.
+Once you have Node installed, you can proceed with installing Gulp's CLI and Yarn.
== Gulp CLI
[.output]
....
-lint:css
-lint:js
+default
+clean
lint
format
build
-build:preview
+bundle
+bundle:pack
preview
-pack
-default
+preview:build
....
We'll explain what each of these tasks are for and when to use them.
projects / working / eg-antora.git / commitdiff