website-v2-docs/antora-ui

= Boost Default UI
// Settings:
:experimental:
:hide-uri-scheme:

This project is the official UI bundle for Boost library documentation, built on Antora.
It provides an interface specifically designed for Boost projects.

It comes ready to be used as-is with Antora for Boost documentation.

== Use the Boost UI

To use the Boost UI for your Antora-generated documentation site, add the following UI configuration to your playbook:

[source,yaml]
----
ui:
  bundle:
    url: https://github.com/boostorg/website-v2-docs/releases/download/ui-master/ui-bundle.zip
    snapshot: true
----

NOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present.
This setting is required because updates to the UI bundle are pushed to the same URL.
If the URL were to be unique, this setting would not be required.

=== UI Options

You can customize the Boost UI by setting the following options in your playbook:

[source,yaml]
----
asciidoc:
  attributes:
    # Enable pagination
    page-pagination: ''
    # Remove the sidenav and include TOC in index.adoc page
    remove-sidenav: ''
    # Include the contents panel with the TOC for the current page
    page-toc: ''
----

== Development Quickstart

This section provides a quick guide to setting up the Boost UI project, previewing it locally, and bundling it for use with Antora.

=== Prerequisites

To preview and bundle the default UI, you need the following software on your computer:

* `git`
* `node` and `npm`
* `gulp`

You can either install `gulp` globally or use the `npx gulp` command.

=== Clone and Initialize the UI Project

Clone the website-v2-docs project.
The UI bundle is located in the `antora-ui` directory.
Stay in this project folder when executing all subsequent commands.

Use npm to install the project's dependencies inside the project.
In your terminal, execute the following command to install dependencies:

[source,sh]
----
npm install
----

=== Preview the UI

The default UI project is configured to preview offline.
The files in the `preview-src` folder provide the sample content that allows you to see the UI in action.
In this folder, you'll primarily find pages written in AsciiDoc.

To build the UI and preview it in a local web server, run the `preview` command:

[source,bash]
----
gulp preview
----

or if using `npx`:

[source,bash]
----
npx gulp preview
----

From now on, you can use `gulp` or `npx gulp` interchangeably.
We'll use `gulp` in the following examples.

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.

You can use `--remove-sidenav` and `--page-toc` flags to customize the preview with options that are typically set in the playbook.

[source,bash]
----
gulp preview --remove-sidenav --page-toc
----

=== Package for Use with Antora

If you need to package the UI, so you can use it to generate the documentation site locally, run the following command:

[source,bash]
----
gulp bundle
----

If lint reports any errors, you'll need to fix them:

[source,bash]
----
gulp format
----

When the command completes successfully, the UI bundle will be available at `build/ui-bundle.zip`.

=== Boost Look

This project uses the Boost color scheme and typography available from `https://github.com/cppalliance/boostlook`.

In the build step, the `boostlook` stylesheet is included in the bundle and used in the UI.
When working on the Antora content, the `boostlook` stylesheet is updated every hour to ensure the latest version is used.

If you're working on the `boostlook.css` file and don't want the build step to include the latest version, you can use the `--skip-boostlook` to ensure the task does not attempt to fetch the latest version.

[source,bash]
----
gulp bundle --skip-boostlook
----

or in preview mode:

[source,bash]
----
gulp preview --skip-boostlook
----

By default, the `boostlook` stylesheet is downloaded from the `master` branch of the `cppalliance/boostlook` repository.
The `BOOSTLOOK_BRANCH` environment variable can be set to use a different branch.

[source,bash]
----
BOOSTLOOK_BRANCH=develop
export BOOSTLOOK_BRANCH
gulp bundle
----

In CI, the `develop` branch is used to ensure the latest version is included in the bundle unless the current branch is `master`.