Documentation UI changes for the overhaul (#2)

- Antora 3 (Rebase with latest upstream changes)
- UI changes for Stackable
- Search integration

Co-authored-by: Dan Allen <dan@opendevise.com>
Co-authored-by: Sven Petersen <s.petersen@webever.de>
Co-authored-by: Guillaume Grossetie <ggrossetie@gmail.com>
Co-authored-by: Edward <edward@encoord.com>

Author: 5 people

.github/workflows/build.yml

@@ -31,4 +31,4 @@ jobs:
           --fail
           -u 'github:${{ secrets.NEXUS_PASSWORD }}'
           --upload-file ./build/ui-bundle.zip
-          "https://repo.stackable.tech/repository/misc/ui-bundle.zip"
+          "https://repo.stackable.tech/repository/misc/antora-ui-bundle.zip"

README.adoc

@@ -29,7 +29,7 @@ It's intentionally minimalistic so as to give you a good starting point without
 
 == Code of Conduct
 
-The Antora project and its project spaces are governed by our https://gitlab.com/antora/antora/-/blob/master/CODE-OF-CONDUCT.adoc[Code of Conduct].
+The Antora project and its project spaces are governed by our https://gitlab.com/antora/antora/-/blob/HEAD/CODE-OF-CONDUCT.adoc[Code of Conduct].
 By participating, you're agreeing to honor this code.
 Let's work together to make this a welcoming, professional, inclusive, and safe environment for everyone.
 
@@ -41,7 +41,7 @@ If you want to simply use the default UI for your Antora-generated site, add the
 ----
 ui:
   bundle:
-    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
 ----
 

docs/antora.yml

@@ -1,5 +1,5 @@
 name: antora-ui-default
 title: Antora Default UI
-version: master
+version: ~
 nav:
 - modules/ROOT/nav.adoc

docs/modules/ROOT/pages/development-workflow.adoc

@@ -2,7 +2,7 @@
 
 // This section provides information about some of the UI files you'll be modifying and how to prepare and submit those changes.
 
-All changes pushed to a UI project's master branch can trigger a new release (not described here).
+All changes pushed to a UI project's default branch can trigger a new release (not described here).
 Therefore, you want to make your changes to a development branch and submit it as a pull request (PR) to be approved.
 (Even better would be to issue the PR from a fork).
 Only when the PR is approved and merged will the new release be triggered.
@@ -11,7 +11,7 @@ Only when the PR is approved and merged will the new release be triggered.
 
 Use the following command to create a local development branch named `name-me`:
 
- $ git checkout -b name-me -t origin/master
+ $ git checkout -b name-me -t origin/HEAD
 
 You'll then apply your changes to the UI files.
 Once you're done making changes, commit those changes to the local branch:
@@ -26,6 +26,6 @@ Finally, navigate to your UI project in your browser and create a new pull reque
 
 The maintainer of the UI should review the changes.
 If the changes are acceptable, the maintainer will merge the pull request.
-As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.
+As soon as the pull request is merged into the default branch, an automated process will take over to publish a new release for the site generator to use.
 
 Now that you've got the process down, let's review some of the files you'll be working with in more detail.

docs/modules/ROOT/pages/index.adoc

@@ -71,15 +71,15 @@ The most common postprocessor backports newer CSS features to older browsers by
 
 == UI project versus UI bundle
 
-The [.term]*UI project*, the master branch of a git repository, contains the recipe and raw materials for creating an Antora UI bundle.
+The [.term]*UI project*, which is comprised of the source files in the git repository, provides the recipe and raw materials for creating an Antora UI bundle.
 It includes a build, source files, project files, and dependency information.
 This is your development workspace.
 
 The [.term]*UI bundle*, a distributable archive, provides pre-compiled (interpreted, consolidated, and/or minimized) files that are ready to be used by Antora.
 
-=== UI project repository structure (master branch)
+=== UI project repository structure (default branch)
 
-You should think of the UI project's master branch as your UI workspace.
+You should think of the UI project's default branch as your UI workspace.
 It contains the recipe and raw materials for creating a UI, including a build, source files, project files, and dependency information.
 
 Here's how the files are structured in the UI project:
@@ -133,7 +133,7 @@ The UI bundle--a distributable archive--provides files which are ready to be use
 When the UI project files are built by Gulp, they are assembled under the [.path]_public_ directory.
 Since the [.path]_public_ directory is generated, it's safe to remove.
 
-The contents of the UI bundle resembles the UI project's master branch contents, except the bundle doesn't contain any files other than the ones that make up the UI.
+The contents of the UI bundle resembles the UI project's default branch contents, except the bundle doesn't contain any files other than the ones that make up the UI.
 This is the content that is used by Antora.
 
 [.output]
@@ -174,7 +174,7 @@ The purpose of an Antora UI project is to get the UI files into a state that Ant
 
 The UI is served statically in a production site, but the UI's assets live in a source form in a UI project to accommodate development and simplify maintenance.
 When handed off to the Antora pipeline, the UI is in an interim, pre-compiled state.
-Specifically, the master branch of the git repository contains the files in source form while releases are used to distribute the files in pre-compiled form.
+Specifically, the default branch of the git repository contains the files in source form while releases are used to distribute the files in pre-compiled form.
 
 The responsibility of compiling the UI is shared between a UI project and Antora.
 The UI project uses a local build to pre-compile (i.e., interpret, consolidate, and/or minimize) the files.

docs/modules/ROOT/pages/set-up-project.adoc

@@ -9,8 +9,8 @@ The sources can be {url-project}[Antora's default UI] or an existing UI project
 To start, clone the default UI project using git:
 
 [subs=attributes+]
- $ git clone {url-project} &&
-   cd "`basename ${_%.git}`"
+ $ git clone {url-project}
+ $ cd "`basename ${_%.git}`"
 
 The example above clones Antora's default UI project and then switches to the project folder on your filesystem.
 Stay in this project folder in order to initialize the project using npm.

docs/modules/ROOT/pages/templates.adoc

@@ -27,7 +27,7 @@ Variable names and purposes may change.
 Here's an overview of the available UI model:
 
 .Variables available to the Handlebars templates (top-level variables in bold)
-[#template-variables-table,cols="1m,2"]
+[#template-variables-ref,cols="1m,2"]
 |===
 | Name | Description
 
@@ -36,6 +36,7 @@ s| [[site]]site
 
 | site.url
 | The base URL of the site, if specified in the playbook.
+If a site start page is defined, the visitor will be redirected from this location to the start page.
 
 | site.path
 | The pathname (i.e., subpath) of the site.url under which the site is hosted (e.g., /docs).
@@ -47,6 +48,9 @@ Can be prepended to `page.url` to create a root-relative URL for a page (e.g., `
 | site.title
 | The title of the site.
 
+| site.homeUrl
+| The URL that points directly to the start (aka home) page of the site.
+
 | site.components
 | A map of all the components in the site, keyed by component name.
 Properties of each component include name, title, url, latest, and versions.
@@ -80,6 +84,9 @@ For example, the value of the document attribute named `page-support-phone` can
 Page attributes can be defined per page in the AsciiDoc document header (e.g., `:page-support-phone: +1 212-555-1234`) or globally in the playbook under the key `asciidoc.attributes`.
 The `page-` prefix is used to isolate page-related attributes from the numerous other document attributes in AsciiDoc.
 
+| page.author
+| The first author of the document, if one or more authors are specified in the AsciiDoc header.
+
 | page.description
 | The text of the description attribute in the AsciiDoc header, if specified.
 
@@ -130,8 +137,8 @@ It's often used as the base URL to generate relative URLs from this page.
 
 | page.canonicalUrl
 | The canonical URL for the current page.
-The canonicalUrl is only set if site.url is set.
-If there are multiple versions of the component, the canonical URL is the qualified URL of the most recent version of the page (excluding any prerelease versions).
+The canonicalUrl is only set if site.url is set to an absolute URL and the page's component has at least one non-prerelease version.
+If there are multiple versions of the component, the canonical URL is the qualified URL of the most recent, non-prerelease version of the page.
 If there's only a single version of the component, the canonical URL is the qualified URL of the current page.
 
 | page.editUrl
@@ -174,6 +181,8 @@ s| env
 
 s| siteRootPath
 | The relative path to the root of the published site.
+If a site start page is defined, the visitor will be redirected from this location to the start page.
+Can be used as a fallback when a site URL is not set.
 
 s| uiRootPath
 | The relative path to the root directory of the UI.
@@ -197,6 +206,6 @@ Next, open the file [.path]_templates/partials/head.hbs_ and add your tag.
 ----
 
 Each template file has access to the template model, which exposes information about the current page through variable names.
-The variables currently available are listed in <<template-variables-table>>.
+The variables currently available are listed in <<template-variables-ref>>.
 
 Save the file, commit it to git, push the branch, and allow the approval workflow to play out.

gulp.d/tasks/build-preview-pages.js

@@ -1,12 +1,6 @@
 'use strict'
 
-// NOTE remove patch after upgrading from asciidoctor.js to @asciidoctor/core
-Error.call = (self, ...args) => {
-  const err = new Error(...args)
-  return Object.assign(self, { message: err.message, stack: err.stack })
-}
-
-const asciidoctor = require('asciidoctor.js')()
+const Asciidoctor = require('@asciidoctor/core')()
 const fs = require('fs-extra')
 const handlebars = require('handlebars')
 const merge = require('merge-stream')
@@ -42,7 +36,7 @@ module.exports = (src, previewSrc, previewDest, sink = () => map()) => (done) =>
             if (file.stem === '404') {
               uiModel.page = { layout: '404', title: 'Page Not Found' }
             } else {
-              const doc = asciidoctor.load(file.contents, { safe: 'safe', attributes: ASCIIDOC_ATTRIBUTES })
+              const doc = Asciidoctor.load(file.contents, { safe: 'safe', attributes: ASCIIDOC_ATTRIBUTES })
               uiModel.page.attributes = Object.entries(doc.getAttributes())
                 .filter(([name, val]) => name.startsWith('page-'))
                 .reduce((accum, [name, val]) => {