Merge branch 'main' into local

docs/modules/ROOT/pages/index.adoc

@@ -1,4 +1,4 @@
-= Antora Default UI
+= Antora Default UI Documentation
 // Settings:
 :hide-uri-scheme:
 // URLs:

docs/modules/ROOT/pages/stylesheets.adoc

@@ -8,7 +8,11 @@ These stylesheets utilize CSS variables to keep the CSS DRY and easy to customiz
 Within the default UI project, the stylesheet files are separated into modules to help organize the rules and make them easier to find.
 The UI build combines and minifies these files into a single file named [.path]_site.css_.
 During the build, the CSS is enhanced using PostCSS in much the same way as a CSS preprocessor works, only the modifications are made to the CSS directly.
-The modifications mostly center around injecting vendor prefixes for compatibility or backporting new features to more broadly supported syntax.
+The modifications mostly revolve around injecting vendor prefixes for compatibility or backporting new features to more broadly supported syntax.
+
+NOTE: An Antora UI provides its own styles.
+While these styles are expected to support any roles defined in the AsciiDoc Language documentation, it does not provide all the selectors found in the Asciidoctor default stylesheet.
+If there's a selector that the Asciidoctor default stylesheet provides that you need in your Antora site, you'll need to add it to the CSS for your own UI.
 
 == Add a new CSS rule
 

docs/modules/ROOT/pages/templates.adoc

@@ -222,3 +222,125 @@ Each template file has access to the template model, which exposes information a
 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.
+
+== Using built-in helpers
+
+Antora provides the following built-in template helpers:
+
+relativize:: Converts a root-relative URL to a URL path that is relative to the current page.
+resolvePageURL:: Resolves the specified page from a page reference and returns the root-relative URL of that page.
+resolvePage:: Resolves the specified page from a page reference, converts it to a UI page model (unless `model=false`), and returns it.
+
+These helpers are available in any Antora UI, not just the default UI.
+
+=== relativize
+
+Antora stores the URL of each publishable resource as a root-relative URL (i.e., /component/version/module/page.html).
+The root in this case is the root of the site (the site URL).
+Antora stores URLs in this way so they can be used to create a relative path from the current page to the target resource, independent of the site's configuration.
+That's the purpose of the `relativize` helper in a template.
+
+.Why use relativize?
+****
+By using relative paths for references, the site is not couple to the URL from which it is served.
+That means the site can be moved around without breaking references.
+It also means the site can be previewed locally without a web server.
+****
+
+You can find the `relativize` helper used throughout the templates in the default UI.
+Here's an example that uses the `relativize` helper to create a relative link to the next page in the navigation.
+
+[,html]
+----
+{{#with page.next}}
+<a href="{{{relativize ./url}}}">{{{./content}}}</a>
+{{/with}}
+----
+
+When creating a link to a URL within the site, you should always wrap it in the `relativize` helper.
+
+=== resolvePageURL
+
+If you want to create a link to another page in your template, you can use the `resolvePageURL` helper.
+This helper resolves the specified page and returns the root-relative URL of that page.
+It's the commplement of the xref macro in the AsciiDoc source.
+
+This helper accepts a page reference, just like the target of the xref macro.
+Internally, this helper uses `ContentCatalog#resolvePage` to resolve the reference.
+The reference will be resolved relative to the module of the page being composed unless broadened by an explicit module, version, or component segment.
+However, since a template is often used by every page in the site, you almost always want this reference to be fully-qualified.
+
+For information about the syntax of a page reference, refer to xref:antora:page:resource-id-coordinates.adoc[resource reference] documentation.
+
+Here's an example that creates a link to another page using the `resolvePageURL` helper.
+
+[,html]
+----
+<a href="{{{relativize (resolvePageURL 'about::support.adoc')}}}">Support</a>
+----
+
+This helper also accepts a context object for specifying the module, version, and component, which can be useful when pages share a common naming pattern.
+
+[,html]
+----
+<a href="{{{relativize (resolvePageURL 'support.adoc' component='about')}}}">Support</a>
+----
+
+The disadvantage of the `resolvePageURL` helper is that it only returns the root-relative URL, not the model of the page.
+If you need more information about the page, such as its title, you can use the `resolvePage` instead.
+
+=== resolvePage
+
+If you want to resolve another page in your template, perhaps to create a link to it, or perhaps to show some information from its model, you can use the `resolvePage` helper.
+This helper resolves the specified page and returns the page model for that page.
+//The page model is the same model used for the `page` variable in the template.
+//In other words, this helper allows you to switch the context of the template to that of another page.
+
+This helper accepts a page reference.
+Internally, this helper uses `ContentCatalog#resolvePage` to resolve the reference.
+
+Here's an example of how to use the `resolvePage` helper to make a link to another page, using the title of that page as the link text.
+
+[,html]
+----
+{{#with (resolvePage 'about::support.adoc')}}<a href="{{relativize ./url}}">{{{./title}}}</a>{{/with}}
+----
+
+This helper also accepts a context object for specifying the module, version, and component, which can be useful when pages share a common naming pattern.
+
+[,html]
+----
+{{#with (resolvePage 'support.adoc' component='about')}}<a href="{{relativize ./url}}">{{{./title}}}</a>{{/with}}
+----
+
+The object returned by the `resolvePage` helper is the UI page model, which is the same model used by the `page` variable.
+You can use the `log` helper inspect the object that this helper returns.
+
+[,html]
+----
+{{log (resolvePage 'about::support.adoc')}}
+----
+
+NOTE: The `resolvePage` helper is typically used inside a `with` block to switch the template's context to the resolved object.
+
+If you want the original virtual file as returned by `ContentCatalog#resolvePage`, you must set the `model=false` argument on the helper.
+Among other things, this gives you access to all the document attributes associated with that page, not just the page attributes.
+
+[,html]
+----
+{{#with (resolvePage 'program::policy-a.adoc' model=false)}}
+<a href="{{relativize ./pub.url}}">{{{./asciidoc.xreftext}}}</a> {{./asciidoc.attributes.next-review-date}}
+{{/with}}
+----
+
+If you need to access the virtual file for the current page, you can do so as follows:
+
+[,html]
+----
+{{#with (resolvePage page.relativeSrcPath model=false)}}
+{{log ./asciidoc.attributes}}
+{{/with}}
+----
+
+Currently, there is no equivalent helper for resolving a non-page resource, but that may be added in the future.
+In the meantime, you could develop your own helper to provide that functionality.

gulp.d/tasks/build.js

@@ -66,7 +66,7 @@ module.exports = (src, dest, preview) => () => {
       // NOTE concat already uses stat from newest combined file
       .pipe(concat('js/site.js')),
     vfs
-      .src('js/vendor/*([^.])?(.bundle).js', { ...opts, read: false })
+      .src('js/vendor/+([^.])?(.bundle).js', { ...opts, read: false })
       .pipe(bundle(opts))
       .pipe(uglify({ output: { comments: /^! / } })),
     vfs

src/css/nav.css

@@ -72,6 +72,10 @@
   height: var(--nav-panel-menu-height);
 }
 
+.nav-panel-menu:only-child {
+  height: 100%;
+}
+
 .nav-panel-menu:not(.is-active) .nav-menu {
   opacity: 0.75;
 }

src/js/01-nav.js

@@ -4,8 +4,8 @@
   var SECT_CLASS_RX = /^sect(\d)$/
 
   var navContainer = document.querySelector('.nav-container')
-  if (!navContainer) return
   var navToggle = document.querySelector('.nav-toggle')
+  if (!navContainer && (!navToggle || (navToggle.hidden = true))) return
   var nav = navContainer.querySelector('.nav')
   var navMenuToggle = navContainer.querySelector('.nav-menu-toggle')