README.adoc

= {extension}-ui ui bundle extension
:extension: aries-antora-ui
:extension-version: 0.0.1

== Description

This ui bundle extension creates the UI bundle for Apache Aries.

== Instructions for Aries site maintenance

The Aries Antora website build uses the packed UI bundle built from these sources.
For the production build, this packed UI bundle must be available from the git repo accessed as a noe module.

=== Production

After you are satisfied with your local changes, run `gulp` and commit your changes and the modified `build/aries-antora-ui-bundle.zip`, and push to GitHub (or GitBox).
Aries website builds will now use the modifed UI.

=== Local development

After making changes, run `gulp;yarn pack`.
This will pack the UI bundle, including both sources and the build bundle, into a .tgz of a node module.
Modify the `package.json` file in `aries-antora` so the `"@apache-aries/aries-antora-ui"` devDependency points to this file.
For instance, on my system, this looks like this:

[source,json]
    "@apache-aries/aries-antora-ui": "file:///Users/david/projects/aries/aries-antora-ui/apache-aries-aries-antora-ui-v0.0.1.tgz"

Running `npm run clean-build` will now build the site with the locally modified UI bundle.

== Generic Usage

To build a ui bundle based on the antora-ui-default sources with the additions from this extension, run `gulp`.

To combine the UI elements from this extension with other elements, using `@djencks/antora-ui-builder`, include in your antora-ui.yml a clause such as:

[source,yml,subs="+attributes]
---
sources:
  - path: antora-ui-default #replace or extend as needed
  - path: @djencks/{extension}-ui
---

Set up your UI project as a ui builder project and include in the `package.json`

[source,json,subs="+attributes"]
---
{
  "name": "...",
  "version": "...",
  "description": "...",
  "main": "gulpfile.js",
  "files": [
    "src/**/*",
    "build/**/*"
  ],
  "devDependencies": {
    "@djencks/antora-ui-builder": "https://experimental-repo.s3-us-west-1.amazonaws.com/djencks-antora-ui-builder-v0.0.1.tgz",
    "antora-ui-default": "git+https://gitlab.com/djencks/antora-ui-default.git#issue-126-requireable",
    "@djencks/{extension}-ui": "https://experimental-repo.s3-us-west-1.amazonaws.com/djencks-{extension}-ui-v{extension-version}.tgz"
  }
}
---