mirror of
https://github.com/boostorg/website-v2-docs.git
synced 2026-01-19 04:42:17 +00:00
153 lines
4.2 KiB
Plaintext
153 lines
4.2 KiB
Plaintext
= 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`.
|