DataStax Antora UI

• Usage
  • About site search UI dependencies
• Development quickstart
  • Prerequisites
  • Clone and initialize the UI project
  • Preview the UI
  • Package for use with Antora
  • Package for use with Antora adding Helios GCX
• Release the UI bundle
  • Release task workflow
• Hero block
  • Define Background css
  • Define the hero block in a .adoc file
• Copyright and license
  • Antora Default UI
  • Branding and design

This project is used to develop and distribute the UI for the DataStax documentation site.

The UI bundle this project produces is intended to be used with Antora. The UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and site-wide images. As such, it provides both the visual theme and user interactions for the documentation site.

The base code for this project is supplied by the {url-antora-default-ui}[Antora Default UI], with DataStax-specific components templated over the top.

Usage

To use this UI with Antora, add the following configuration to your playbook file:

ui:
  bundle:
    url: https://github.com/riptano/antora-ui-docs/releases/latest/download/ui-bundle.zip
    snapshot: true

📎	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.

About site search UI dependencies

Additional tasks must be performed in order for the site search functionality on docs.datastax.com to work properly. These tasks only need to be performed when changes are made to the following files:

Files	Tasks
gcx/algoliaSearch/index.html	Copy this file to the /en/search directory on the coppi and docs-preview servers.
gcx/algoliaSearch/src/*	Copy these files to the playbooks/supplemental-ui directory in the docs-home repository.

In the docs-home repository, the site-local-home.yaml and site-publish-home.yaml playbooks are configured to incorporate the files from the supplemental-ui directory into the assets directory of the generated site:

ui:
  supplemental_files:
  - path: css/siteSearch.css
    contents: ./supplemental-ui/siteSearch.css
  - path: js/siteSearch.js
    contents: ./supplemental-ui/siteSearch.js
  output_dir: assets

Whenever files are changed or added within the supplemental-ui directory, the home docset must then be built and deployed to all of the docs servers to ensure that the servers have the latest site search assets.

bsys build home
bsys deploy home coppi
bsys deploy home docs-preview
bsys sync

coppi asset locations

/var/www/en/home/assets/css/siteSearch.css
/var/www/en/home/assets/js/siteSearch.js

docs-preview asset locations

/datastax/www/docs.datastax.com/en/home/assets/css/siteSearch.css
/datastax/www/docs.datastax.com/en/home/assets/js/siteSearch.js

Development quickstart

This section offers a basic tutorial to teach you how to set up the UI project, preview it locally, and bundle it for use with Antora. A more comprehensive tutorial can be found in the documentation at {url-antora-docs}.

Prerequisites

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

• git (command: git)

• {url-nodejs}[Node.js] (commands: node and npm)

• Gulp CLI (command: gulp)

git

First, make sure you have git installed.

git --version

If not, download and install the git package for your system.

Node.js

Next, make sure that you have Node.js installed (which also provides npm).

node --version

If this command fails with an error, you don’t have Node.js installed. If the command doesn’t report an LTS version of Node.js (e.g., v16.17.1), it means you don’t have a suitable version of Node.js installed. In this guide, we’ll be installing Node.js 16.

While you can install Node.js from the official packages, we strongly recommend that you use nvm (Node Version Manager) to manage your Node.js installation(s). Follow the nvm installation instructions to set up nvm on your machine.

Once you’ve installed nvm, open a new terminal and install Node.js 16 using the following command:

nvm install 16

You can switch to this version of Node.js at any time using the following command:

nvm use 16

To make Node.js 16 the default in new terminals, type:

nvm alias default 16

Now that you have Node.js installed, you can proceed with installing the Gulp CLI.

Gulp CLI

You’ll need the Gulp command-line interface (CLI) to run the build. The Gulp CLI package provides the gulp command which, in turn, executes the version of Gulp declared by the project.

You can install the Gulp CLI globally (which resolves to a location in your user directory if you’re using nvm) using the following command:

npm install -g gulp-cli

Verify the Gulp CLI is installed and on your PATH by running:

gulp --version

If you prefer to install global packages using Yarn, run this command instead:

yarn global add gulp-cli

Alternately, you can use the gulp command that is installed by the project’s dependencies.

$(npm bin)/gulp --version

Now that you have the prerequisites installed, you can fetch and build the UI project.

Clone and initialize the UI project

Clone the UI project using git:

git clone https://github.com/riptano/antora-ui-docs &&
 cd "`basename $_`"

The example above clones the UI project and then switches to the project folder on your filesystem. Stay in this project folder when executing all subsequent commands.

If you are testing UI bundle changes from a PR that is not yet merged to main, checkout the branch. Example:

git checkout feature/new-helios-base

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

npm install

This command installs the dependencies listed in package.json into the node_modules/ folder inside the project. This folder does not get included in the UI bundle and should not be committed back to this repository.

Tip	If you prefer to install packages using Yarn, run this command instead: yarn

Preview the UI

This UI project is configured to preview offline. The files in the preview-src/ folder provide the sample content that allow you to see the UI in action. In this folder, you’ll primarily find pages written in AsciiDoc. These pages provide a representative sample and kitchen sink of content from the real site.

If you are testing UI bundle changes from a PR that is not yet merged to main, and if you haven’t already, remember to checkout the branch. Example:

git checkout feature/new-helios-base

Run the npm install command again.

npm install

Now, to build the UI and preview it in a local web server, run the preview command:

gulp preview

You’ll see a URL listed in the output of this command:

[12:00:00] Starting server...
[12:00:00] Server started http://localhost:5252
[12:00:00] Running server

Navigate to this URL to preview the site locally.

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 preview:build task if a change is detected, and sending the updates to the browser.

Press Ctrl+C to stop the preview server and end the continuous build.

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:

gulp bundle

If any errors are reported by lint, you’ll need to fix them.

When the command completes successfully, the UI bundle will be available at build/ui-bundle.zip. You can point Antora at this bundle using the --ui-bundle-url command-line option.

If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:

gulp bundle:pack

The UI bundle will again be available at build/ui-bundle.zip.

Package for use with Antora adding Helios GCX

To include Helios GCX to the Antora bundle, you can build it following these steps:

Install the Node dependencies from the ./gcx folder:

cd ./gcx
npm install

Once it finished, you can run on this folder:

npm run bundle

This script will run both Antora and Helios bundlers, the final build you can find it on ./gcx/build as ui-bundle.zip

Source maps

The build consolidates all the CSS and client-side JavaScript into combined files, site.css and site.js, respectively, in order to reduce the size of the bundle. {url-source-maps}[Source maps] correlate these combined files with their original sources.

This “source mapping” is accomplished by generating additional map files that make this association. These map files sit adjacent to the combined files in the build folder. The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.

In preview mode, source maps are enabled automatically, so there’s nothing you have to do to make use of them. If you need to include source maps in the bundle, you can do so by setting the SOURCEMAPS environment variable to true when you run the bundle command:

SOURCEMAPS=true gulp bundle

In this case, the bundle will include the source maps, which can be used for debugging your production site.

Release the UI bundle

Once you’re satisfied with the changes you’ve made to the UI and would like to make those changes available to Antora, you’ll need to publish the UI as a bundle by making a release. The bundle can then be downloaded from this repository using a unique URL. You can see a list of all past releases on the releases page.

📎	All DataStax docs are configured to pull the latest, non-pre-release UI bundle. See the Usage section for an example of how this behavior is configured in a site playbook.

Release task workflow

In addition to the Prerequisites covered above, you’ll need to complete the following steps to release a new UI bundle:

1. Pack the UI bundle as described in Package for use with Antora.

   gulp bundle

2. Follow the GitHub instructions for {url-create-release}[creating a release].

   1. Create a new tag using the next version number in the sequence (e.g., prod-2 after prod-1)

   2. Make sure that the new tag targets the main branch.

   3. Title the release with the same name as the tag. (The release title and the tag name should always be the same, as it makes releases easier to identify.)

   4. (Optional) Add a description for the release that highlights the functional changes that have been added since the last release.

   5. Attach the UI bundle, located in gcx/build/ui-bundle.zip`, as a release asset.

   6. Check the box labeled This is a pre-release if you don’t want the release to be generally available.

      Selecting this option is helpful if you want to publish a new UI bundle for testing purposes (production builds of the DataStax documentation are only configured to consume the latest non-pre-release UI bundle). You can then edit the release in the future to remove the Pre-release label, if desired.

      Caution

      If you do not check this box, then the release is immediately promoted to Latest, and all DataStax docs will consume the new UI bundle the next time they are built.

3. Update the :current-release: attribute in the header of this README to reference the tag of the latest bundle (if it is not pre-release), then commit that update to the repository.

Hero block

There are two files that need to be updated in order to include the hero block in a page

• helios-gcs-heroBlock.css

• The .adoc file you want to add the hero block

Define Background css

1. To define the hero block background, it needs to be done in the helios-gcs-heroBlock.css file located under /gcx/styles/src/css/ path

2. It requires to set the class identifier name/value and the path to the background image which can be an svg file.

3. The class identifier name/value would be any meaningful value you would like to use to identify the background image.

   1. The identifier name will be used to reference the background image in the .adoc where the hero will be setup.

   2. If the identifier name is not defined, it will use the default setup image.

For the below code portion .dsHeroBlock, .dsHeroBlock[data-banner="default"] would be the default image to set in case no identifier or "default" identifier is set

.dsHeroBlock,
.dsHeroBlock[data-banner="default"] {
    background-image: url('../img/hero-banner-1.svg');
    background-size: cover;
    color: white;
    font-family: 'Roboto', sans-serif;
  }

To set a specific background image, it will be done by setting the identifier value and the image path

.dsHeroBlock[data-banner="alternative"]{
  background-image: url('../img/hero-banner-2.svg');
}

Define the hero block in a .adoc file

The structure to set a hero block in an .adoc file is as shown in the code block below. This will add the hero block to the top of the page which will have a background, title, content.

1. Hero Block background (class="dsHeroBlock")

   1. This is set by adding <div class="dsHeroBlock" data-banner="alternative"> where the "data-banner identifier will be the name especified for the image in the helios-gcs-heroBlock.css file.

2. [.hero.title]

   1. This tag is used to set the hero banner title

3. [.hero.content]

   1. This tag is used to set the hero banner content under the title.

++++
<div class="dsHeroBlock" data-banner="alternative">
++++

[.hero.title]
Documentation Home

[.hero.content]
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

++++
</div>
++++

Copyright and license

Antora Default UI

Copyright © 2017-present OpenDevise Inc. and the Antora Project.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).

Branding and design

Copyright © DataStax 2021-present. All rights reserved.