Merge branch 'stackable' into docs/building

# Conflicts:
#	README.adoc

Author: lfrancke

.github/workflows/build.yml

@@ -8,12 +8,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
         with:
           node-version: '16'
       - name: Cache Node.js modules
-        uses: actions/cache@v2
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
         with:
           path: ~/.npm
           key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}

README.adoc

@@ -9,26 +9,37 @@
 :url-antora-docs: https://docs.antora.org
 :url-git: https://git-scm.com
 :url-git-dl: {url-git}/downloads
-:url-gulp: http://gulpjs.com
 :url-opendevise: https://opendevise.com
 :url-nodejs: https://nodejs.org
 :url-nvm: https://github.com/creationix/nvm
 :url-nvm-install: {url-nvm}#installation
 :url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
 
-This project is the UI template used on {url-stackable-docs}[the Stackable docs]. It is based on the {url-default-ui}[Antora default UI]. As intended, this repository is forked from the 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.
+This project is the UI template used on {url-stackable-docs}[the Stackable docs].
+It is based on (forked from) the {url-default-ui}[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
 
-`npm` is required. We recommend `nvm` to install `npm`, see the Default UI README for instructions on how to install it.
+=== Prerequisites
 
-Run
+To preview and bundle the default UI, you need the following software on your computer:
 
+* {url-git}[git] (command: `git`)
+* {url-nodejs}[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:
 [source,js]
 npm ci
 npm run bundle
 
-to create a bundle. It will be created in `build/ui-bundle.zip`
+It will be created in `build/ui-bundle.zip`
 
 == Project structure
 
@@ -43,15 +54,13 @@ Inside the `src` directory are:
 * `layouts`: TODO
 * `partials`: Contains all the Handlebars files. This is the directory containing all the templated HTML for the site.
 
-== Build process
-
-The UI is built with Gulp. Linting, bundling and previewing is supported. This repository is referenced as a submodule in the documentation repository and the bundling takes place there.
-
 === Gulp
 
-To work on the build process of this, you need to understand [gulp](https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles). Gulp is a builder/bundler that is used to package this antora UI.
+To work on the build process of this, you need to understand [gulp](https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles).
+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.
+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`)
 
@@ -66,12 +75,14 @@ ui:
 
 === Previewing the UI during development
 
-It is useful to be able to see changes quickly while working on the UI. To start the preview at http://localhost:5252, run `npm run preview`.
+It is useful to be able to see changes quickly while working on the UI.
+To start the preview at http://localhost:5252, run `npm run preview`.
 Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
 ==== How it works
 
-The `preview-src` directory contains dummy docs content which will be used to render the UI templates. The `ui-model.yml` contains dummy information similar to the antora-playbook.yaml.
+The `preview-src` directory contains dummy docs content, which will be used to render the UI templates.
+The `ui-model.yml` contains dummy information similar to the antora-playbook.yaml.
 
 == Notes on our Customized Version
 
@@ -81,6 +92,12 @@ We have added our own tracking solution into `src/partials/head-scripts.hbs`. It
 === Highlight.js v10
 [Ticket](https://github.com/stackabletech/documentation/issues/232) - Due to the removal of HTML-passthru in v11 (which we need for [Callouts](https://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 https://pagefind.app/[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 (C) 2017-present OpenDevise Inc. and the Antora Project.

gulp.d/tasks/build.js

@@ -37,7 +37,7 @@ module.exports = (src, dest, preview) => () => {
       }),
     postcssUrl([
       {
-        filter: '**/~typeface-*/files/*',
+        filter: '**/~@fontsource/*/files/*',
         url: (asset) => {
           const relpath = asset.pathname.substr(1)
           const abspath = require.resolve(relpath)