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 |
Main Menu and Drop Downs
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. |
Menu One
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>
Menu Two
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 Three
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>
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