Skip to content

Latest commit

 

History

History
72 lines (42 loc) · 2.61 KB

README.adoc

File metadata and controls

72 lines (42 loc) · 2.61 KB
Raw

Eclipse Jetty Website Playbook

This repository is for the development of the new jetty.org website.

The staged site is available at the following URL:

Prerequisites

The site is built using Antora. This directory contains a Maven project that uses the Antora Maven plugin. This plugin allows you to run Antora through Maven. The only prerequisite is that you have Maven installed on your machine.

You do not need to have Node.js or npm installed. You also don’t need to run npm install. The Antora Maven plugin handles all this.

Usage

To build the site quickly, use:

$ mvn antora

Antora will print the location of the generated site in the Maven log.

To ensure everyone is using the same environment, you may want to use the Maven wrapper, mvnw to invoke Maven instead:

$ ./mvnw antora

On the first run, this command will set up Node.js (in target/node) and install the project dependencies (npm packages) (into node_modules).

Note

The previous command is roughly equivalent to the following low-level npx command:

$ npx antora --clean --fetch antora-playbook.yml

In order to use npx directly, you must have Node.js preinstalled.

You can pass options directly to Antora by defining user properties that start with antora.option.. For example, you can enable the jetty-downloads extension as follows:

$ mvn antora -Dantora.option.extension[1]=jetty-download

Antora is configured to fetch the remote repositories on each run. If you want to work offline after the first run, you can unset the fetch option:

$ mvn antora -Dantora.option.fetch?=false

You can accomplish the same thing by enabling the cached execution profile, which overrides options passed to Antora.

$ mvn antora:antora@cached

To activate the diagram generator (Kroki), enable the kroki execution profile.

$ mvn antora:antora@kroki

If you want to run the full production build, enable the full execution profile.

$ mvn antora:antora@full

The full production build is equivalent to the following npm and npx command:

$ npm i --package-lock false
  ANTORA_CACHE_DIR=$PWD/.cache/antora npx --offline antora --clean --fetch --extension @antora/collector-extension --extension @antora/lunr-extension --extension jetty-downloads --extension register-asciidoctor-kroki --extension ./lib/router-extension.js --log-failure-level warn --stacktrace antora-playbook.yml

The Maven plugin also prints the npx command before running it for informational purposes and to help you debug the configuration.