Skip to content

ui

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

ui

README.adoc

Stackable UI based on Antora Default UI

This project is the UI template used on the Stackable docs. It is based on (forked from) the Antora default UI and customized to our needs. The document below contains information about this repo, but consult the default UI README as well for additional useful information.

Quickstart

Prerequisites

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

  • git (command: git)

  • Node.js (commands: node and npm)

Build process

The UI is built with Gulp. Linting, bundling, and previewing are supported. This repository is referenced as a submodule in the documentation repository, and the bundling takes place there.

To create a bundle run:

npm ci
npm run bundle

It will be created in build/ui-bundle.zip

Project structure

The UI bundle is basically a collection of handlebars templates and some minimal JS and CSS, which is then filled with life with the documentation content. All of this lives in the src directory.

Inside the src directory are:

  • css: Contains all the CSS. site.css contains imports of all the other files. In vendor there is the copied-in FontAwesome CSS file.

  • helpers: Contains Handlebars helper functions. The file names are the names of the helpers. You can use these inside the Handlebars templates.

  • img: Images used in the UI.

  • js: Contains JavaScript files for UI functionality, numbered for loading order. The vendor directory contains third-party libraries like highlight.js and tabs functionality.

  • layouts: Contains the main Handlebars layout templates. default.hbs is the standard page layout, landing.hbs is for landing pages with special styling, and 404.hbs handles error pages. These templates define the overall page structure and include partials for header, body, and footer.

  • partials: Contains all the Handlebars files. This is the directory containing all the templated HTML for the site.

Build

npm run bundle runs build.mjs: Vite builds the css (one pass) and each js entry (one pass per file, as self-contained classic scripts), the static directories are copied in, and everything is zipped into build/ui-bundle.zip.

The js entries are js/site.js (the numbered scripts under src/js, concatenated in order) and one js/vendor/<name>.js per src/js/vendor/<name>.bundle.js with its imports bundled in.

Building the final documentation

The build is wired into the Playbooks of this repository:

ui:
  bundle:
    url: ./ui/build/ui-bundle.zip

To see UI changes rendered with real content, build the site: make build-truly-local (or push and use the deploy preview).

Notes on our Customized Version

Tracking

We have added our own tracking solution into src/partials/head-scripts.hbs. It has the URL hardcoded. it can be enabled by setting site.keys.enable_tracking to true/false in the Antora playbook.

Highlight.js v10

[Ticket](github.com/stackabletech/documentation/issues/232) - Due to the removal of HTML-passthru in v11 (which we need for [Callouts](docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/)) the highlight.js has not been updated from v10. This also affects the Antora Default UI. Both decisions will be revisited when the upstream upgrade is available.

Search with pagefind

We use pagefind for search. The index is generated as part of the build in the documentation repository. Various pagefind-* tags are used to mark content that should be indexed. Only the stable docs are indexed (no previous versions, no nightly).

Copyright and License

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). See LICENSE to find the full license text.

Authors

Development of Antora is led and sponsored by OpenDevise Inc.