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.
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 bundleIt will be created in build/ui-bundle.zip
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.csscontains imports of all the other files. Invendorthere 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. Thevendordirectory contains third-party libraries like highlight.js and tabs functionality. -
layouts: Contains the main Handlebars layout templates.default.hbsis the standard page layout,landing.hbsis for landing pages with special styling, and404.hbshandles 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.
To work on the build process of this, you need to understand gulp. Gulp is a builder/bundler that is used to package this antora UI.
In this project, gulpfile.js is the main entrypoint for gulp.
This file references tasks in the gulp.d directory.
You don’t need to install the gulp CLI yourself, you can call package scripts (i.e. npm run bundle which will then call gulp from the node_modules).
The documentation repository uses this repository as a submodule, bundles the UI on demand and then links to it like this in the Playbook:
ui:
bundle:
url: ./ui/build/ui-bundle.zipIt is useful to be able to see changes quickly while working on the UI.
To start the preview at localhost:5252, run npm run preview.
Press Ctrl+C to stop the preview server and end the continuous build.
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.
[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.
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 © 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.
Development of Antora is led and sponsored by OpenDevise Inc.