Getting Started

Last Updated: 2022-09-06

Playbook Setup - UI Keys

Basic Setup

The playbook keys configured under ui define the location of the UI bundle and control how it’s processed.

ui:
  bundle:
    url: https://lightbend.github.io/antora-supplemental-ui-lightbend-theme/default_ui/lightbend-theme-ui-001-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental_ui

Above we reference a publically avialible UI Bundle ZIP that’s been tested against the Lightbend Theme. When Antora releases new Default UI bundles, we will test and host new bundles and document them here.

This is the latest: https://lightbend.github.io/antora-supplemental-ui-lightbend-theme/default_ui/lightbend-theme-ui-001-bundle.zip

We also define the location of the supplemental_files directory.

Override Default Layout

You can define an optional default_layout in the playbook that will be applied globally to the docs that are generated. In the example below we tell Antora to use default-dev, a custom handlebar file that replaces default.hbs that lives in supplemental_ui/layouts.

ui:
  bundle:
    url: https://lightbend.github.io/antora-supplemental-ui-lightbend-theme/default_ui/lightbend-theme-ui-001-bundle.zip
    snapshot: true
  default_layout: default-dev
  supplemental_files: ./supplemental_ui

For more info on configuring the playbook: https://docs.antora.org/antora/2.3/playbook/configure-ui/

Supplemental Files

The Lightbend theme uses supplemental files to extend Antora’s default ui. This includes additional scripts, stylesheets and handlebar files (templated HTML). The handlebar files can be adjusted to your specific needs, such as changing navigation menu urls, logos, inline javascript such as embeds, tag manager, code highlighting and cookie banner code.

Latest CSS

You can find the latest minified Theme CSS file in the following folder https://github.com/lightbend/antora-supplemental-ui-lightbend-theme/tree/master/dist/css. Please copy the latest CSS file to your supplemental_ui/css folder, do not reference these files directly.

Default Layout(s)

We can extend Antora’s default.hbs:

<!DOCTYPE html>
<html lang="en">
  <head>
{{> head defaultPageTitle='Untitled'}}
  </head>
  <body class="article{{#with (or page.attributes.role page.role)}} {{{this}}}{{/with}}">
{{> header}}
{{> body}}
{{> footer}}
  </body>
</html>

By adding any of the following three CSS classes: class="hide-versions hide-edit-this-page blue-theme…​. to the <body> tag, you can change the visual behaviour of the theme.

<body class="hide-versions hide-edit-this-page blue-theme article{{#with (or page.attributes.role page.role)}} {{{this}}}{{/with}}">

blue-theme will turn the theme to a blue skin for OSS websites. The default skin uses Lightbend Orange for commercial documentation. hide-versions will hide the version UI element at the bottom of the main table of contents.
hide-edit-this-page will hide the 'Edit This Page' link that appears in the grey toolbar.

hide-edit-this-page requires theme.1.0.2.min.css or greater to function

The following examples map to the menus in this theme guide, please refer to the main menu above to see the rendered results.

The examples show the navbar-item html element and how you can construct different drop downs, menu links and menu buttons. They are located in the header-content.hbs partial located in the supplemental_ui directory.

In order for the buttons to style correctly, you’ll need theme.1.1.3.min.css or greater installed in your doc repo.

Two column menu with a section heading for the first column. If the second column does not have a section header, as shown in this example, give said section a class of no-header.

<div class="navbar-item has-dropdown is-hoverable">
  <span class="navbar-link">Menu One</span>
  <div class="navbar-dropdown">
    <section>
      <header>Section One</header>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
    </section>
    <section class="no-header">
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
    </section>
  </div>
</div>

Simple single column menu, no section heading, Primary Button example.

<div class="navbar-item has-dropdown is-hoverable">
  <span class="navbar-link">Menu Two</span>
  <div class="navbar-dropdown">
    <section>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#">Menu Item</a>
        <a href="#" class="btn">Primary Button</a>
    </section>
  </div>
</div>

Menu showing the different ways you can mark-up buttons in the drop downs. A standard a link requires at minimum the btn css class. This will style link as a Primary Button. Adding blue will style the button blue as is considered a Secondary Button. Give the link a class of full-width and it will span the entire section column.

<div class="navbar-item has-dropdown is-hoverable">
  <span class="navbar-link">Menu Three</span>
  <div class="navbar-dropdown">
    <section>
        <a href="{{siteRootUrl}}index.html#main-menu-and-drop-downs">Button examples, see Getting Started.</a>
        <a href="#" class="btn blue">Blue Button</a>
        <a href="#" class="btn">Primary Button</a>
        <a href="#" class="btn full-width">Full Width Button</a>
    </section>
  </div>
</div>

When there is no need for a drop down and want to link directly from a top level menu link.

<div class="navbar-item">
  <a href="" class="navbar-link">Menu Link</a>
</div>

In this example we show a Register / Log in button. The markup requires the additional btn css class.

<div class="navbar-item">
  <a href="" class="navbar-link btn">REGISTER / LOG IN</a>
</div>

Page Setup - Optional Settings

:page-description: Your custom page description goes here
:page-social-share-image: https://downloads.lightbend.com/website/social/lightbend-logo-orange-twitter.jpg
:page-supergroup-java-scala: Language
:page-supergroup-sbt-maven: Build Tool
:page-supergroup-sbt-maven-gradle: Build Tool
:page-supergroup-minishift-minikube: Platform
:page-supergroup-kubernetes-openshift: Platform
:page-supergroup-mac-ubuntu: OS
:page-supergroup-browser-cli: Interface