This project is used to develop and distribute the UI for the Redpanda documentation site. The UI bundle this project produces is intended to be used with Antora. The UI bundle contains the HTML templates, CSS, JavaScript, fonts, and site-wide images. The rest of the material for the documentation site comes from the playbook repository and content repositories.
To use this UI with Antora, add the following configuration to your playbook file:
ui:
bundle:
url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zipIn this section, you learn how to set up the UI project, preview it locally, and bundle it for use with Antora.
To preview and bundle the UI, you need the following software on your computer:
Make sure you have git installed.
git --versionIf not, download and install the git package for your system.
you must have Node.js 16 or higher installed on your machine.
node --versionIf this command fails, you don’t have Node.js installed.
You’ll need the Gulp command-line interface (CLI) to run the build.
This package provides the gulp command which, in turn, executes the version of Gulp declared by the project.
You should 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-cliVerify the Gulp CLI is installed and on your PATH by running:
gulp -vNow that you have the prerequisites installed, you can fetch and build the UI project.
Clone the UI project using git:
git clone https://github.com/redpanda-data/docs-ui
cd docs-uiThe example above clones the Redpanda docs UI project and then switches to the project directory on your filesystem. Stay in this project directory when executing all subsequent commands.
Use npm to install the project’s dependencies inside the project. In your terminal, execute the following command:
npm installThis command installs the dependencies listed in package.json into the node_modules/ directory inside the project.
This directory does not get included in the UI bundle and should not be committed to the source control repository.
The UI project is configured to preview offline.
The files in the preview-src/ directory provide the sample content that allows you to see the UI in action.
In this directory, you’ll primarily find pages written in AsciiDoc.
These pages provide a representative sample and kitchen sink of content from the real site.
To build the UI and preview it in a local web server, run the preview command:
gulp previewYou’ll see a URL listed in the output of this command:
[17:32:55] Starting 'preview:serve'... [17:32:55] Starting server... [17:32:55] Server started http://localhost:5252 and http://192.168.1.3:5252 [17:32:55] 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 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.
If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
gulp bundleIf 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 or in the ui.bundle.url property of the playbook file.
To control the visual appearance of pages, the UI bundle provides a CSS stylesheet (for changing the CSS style rules) and any number of layouts in the form of Handlebars templates (for changing the HTML). Although most styles are used on all pages, it’s possible to configure styles to target certain pages based on the layout. This section will introduce these various options and explain how they work.
The most drastic way to change the appearance of the page is to change the HTML. The HTML is controlled by layouts, which are Handlebars templates located in src/layouts. A layout typically includes partials, located in src/partials, which are reusable template fragments. Partials may, in turn, include other partials.
This project currently has six layouts:
-
default.hbs
-
404.hbs
-
home.hbs
-
index.hbs
-
search.hbs
-
swagger.hbs
If a page doesn’t specify a layout, the default.hbs layout is used.
To specify a layout, the page file must declare the page-layout document attribute in the AsciiDoc header.
The value of that attribute should match the stem of the layout file (the filename minus the file extension, such as home).
For example, the home page declares the following document attribute in the AsciiDoc header:
= Redpanda Documentation
:page-layout: homeIn this case, Antora will select the home.hbs layout for this page instead of default.hbs.
Using a dedicated layout affords a lot of control over what gets displayed on this page.
Every layout has access to the same UI model.
The home page likely requires additional styles that are only relevant to that page.
You can organize these styles inside a namespace by adding a dedicated class to the <body> tag.
In fact, that’s what the home.hbs layout currently does.
<body class="home">
...
</body>You can now define styles that are scoped to that page as follows:
.home h1,
.home h2,
.home h3 {
line-height: 1.2;
margin: 0;
}To make these styles easier to find and manage, they should be organized in a dedicated file src/css/home.css and included in the master src/css/site.css file, which is how this project is currently configured.
When you run the preview, you can see the home page by visiting the URL http://localhost:5002/home.html.
You can create an arbitrary number of pages for the preview site.
To make a page, create a new AsciiDoc file inside the preview-src directory.
You can then access the page in the preview site using the URL pattern http://localhost:5252/<stem>.html, where <stem> is the stem of the source file (the filename minus the file extension).
These preview pages serve the purpose of testing the page layout and content styling. Each page may declare a layout, role, or both.
The only caveat is that, at the moment, every page provides the same UI model (with a few exceptions).
The model is defined in preview-src/ui-model.yml file.
The exceptions include the layout, role, title, contents, and, in the case of home.adoc, the component, which get updated dynamically by the build.
For information about what goes in the UI model, refer the Handlebars templates page in the Antora documentation.
This UI provides integration with Algolia search.
The Algolia client is configured in the files src/partials/algolia-script.hbs and src/layouts/search.hbs.
You can test the search directly from the preview site by setting the following environment variables in your shell:
-
ALGOLIA_APP_ID- the application ID that hosts the search index -
ALGOLIA_API_KEY- your API key for Algolia -
ALGOLIA_INDEX_NAME- the name of the index
You can point to any index that is publicly accessible.
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. This project provides a GitHub Action that fully automates the release.
Whenever you push a new tag to this repository, the GitHub Action will generate a new release and bundle the UI before publishing the bundle to the releases section of the repository on GitHub. The bundle can then be downloaded using a unique URL, accessible from the release page. You can see a list of all past releases on the releases page.
If you’re trying to bundle the UI on Windows, Visual Studio Code can output this error message: Cannot be loaded because running scripts is disabled on this system. To fix this problem, follow the steps in this post.
The software in this repository (build scripts, JavaScript files, Handlebars templates, foundation CSS, utility icons, etc) is part of the Antora project. As such, the use of the software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).
Copyright © Redpanda 2023. All rights reserved.