Merge branch 'main' into local

docs/modules/ROOT/nav.adoc

@@ -10,6 +10,7 @@
  ** xref:add-fonts.adoc[]
 * xref:style-guide.adoc[]
  ** xref:inline-text-styles.adoc[]
+ ** xref:image-styles.adoc[]
  ** xref:admonition-styles.adoc[]
  ** xref:code-blocks.adoc[]
  ** xref:list-styles.adoc[]

docs/modules/ROOT/pages/add-fonts.adoc

@@ -21,7 +21,7 @@ Here are the steps involved.
 
 . Use npm (or Yarn) to install the font files from a package (e.g., https://www.npmjs.com/package/typeface-open-sans[typeface-open-sans])
 
- $ npm install --save typeface-open-sans
+ $ npm i --save typeface-open-sans
 
 . In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
 . In that file, declare the font face:
@@ -64,7 +64,7 @@ TIP: If you're building on the default UI, you may instead want to define or upd
 
 . Test the new font by previewing your UI:
 
- $ gulp preview
+ $ npx gulp preview
 
 If you see the new font, you've now successfully added it to your UI.
 If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.
@@ -117,7 +117,7 @@ TIP: If you're building on the default UI, you may instead want to define or upd
 
 . Test the new font by previewing your UI:
 
- $ gulp preview
+ $ npx gulp preview
 
 If you see the new font, you've now successfully added it to your UI.
 If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.

docs/modules/ROOT/pages/build-preview-ui.adoc

@@ -20,7 +20,7 @@ The next two sections explain how to use these modes.
 
 To build the UI once for preview, then stop, execute the following command:
 
- $ gulp preview:build
+ $ npx gulp preview:build
 
 This task pre-compiles the UI files into the [.path]_public_ directory.
 To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_).
@@ -32,7 +32,7 @@ This task also launches a local HTTP server so updates get synchronized with the
 
 To launch the preview server, execute the following command:
 
- $ gulp preview
+ $ npx gulp preview
 
 You'll see a URL listed in the output of this command:
 
@@ -53,7 +53,7 @@ Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
 If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
 
- $ gulp bundle
+ $ npx gulp bundle
 
 The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
 
@@ -62,6 +62,6 @@ You can then point Antora at this bundle using the `--ui-bundle-url` command-lin
 
 If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:
 
- $ gulp bundle:pack
+ $ npx gulp bundle:pack
 
 The UI bundle will again be available at [.path]_build/ui-bundle.zip_.

docs/modules/ROOT/pages/image-styles.adoc

@@ -0,0 +1,59 @@
+= Image Styles
+:navtitle: Images
+
+This page describes how images in the content are styled and how to customize these styles.
+It covers both block and inline images, which are styled differently.
+
+[#size]
+== Image size
+
+If a width is not specified on the image macro, the image will be sized to match its intrinsic width.
+However, if that width exceeds the available width (i.e., the width of the content area), the image's width will be capped to fit the available space (`max-width: 100%`).
+
+If the image is an SVG, and a width is not specified on the image macro or on the root tag in the SVG, the image will use the maximum width available (i.e., the width of the content area).
+
+The image's height is not used when sizing the image.
+However, the aspect ratio of the image is preserved.
+
+[#block-position]
+== Block image position
+
+By default, a block image is centered within the content area of the page.
+If the block has a caption, that caption will also be centered under the image, but the text will be left-aligned.
+The caption may exceed the width of the image.
+
+If you want the image and its caption to be aligned to the left side of the content, add the `text-left` role to the image block.
+
+[,asciidoc]
+----
+[.text-left]
+image::my-image.png[]
+----
+
+If you want the image and its caption to be aligned to the right side of the content, add the `text-right` role to the image block.
+
+[,asciidoc]
+----
+[.text-left]
+image::my-image.png[]
+----
+
+Applying the `text-right` role also flips the text alignment of the caption to right-aligned.
+
+== Float an image
+
+You can float either a block or inline image to the left or right using the `float` attribute.
+When an image is configured to float, the content that follows it will wrap around it (on the opposing side) until that content clears the bottom of the image.
+
+Typically, you use the `float` property with an inline image since you can control when the floating starts relative to the surrounding content.
+
+[,asciidoc]
+----
+image:subject.png[Subject,250,float=right]
+This paragraph can refer to the image on the right.
+----
+
+If you use `float` on a block image, it overrides its default positioning (it will be aligned in the direction of the float).
+
+Using float implies that the image occupies less than the width of the content area.
+If, on the other hand, it extends from margin to margin, than it ceases to function as a float.

docs/modules/ROOT/pages/index.adoc

@@ -54,6 +54,11 @@ npm manages software packages (i.e., software dependencies) that it downloads fr
 Software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages.
 npm is part of Node.js.
 
+npx (command: `npx`)::
+npx runs bin scripts that are either installed in [.path]_node_modules/.bin_ or that it manages itself (if there's no package.json).
+npx is the preferred way to run any command.
+npx is part of Node.js.
+
 package.json:::
 This file keeps track of the dependencies (described using fuzzy versions) that npm (or Yarn) should fetch.
 

docs/modules/ROOT/pages/prerequisites.adoc

@@ -10,9 +10,9 @@
 
 An Antora UI project is based on tools built atop Node.js, namely:
 
-* {url-node}[Node.js] (commands: `node` and `npm`)
+* {url-node}[Node.js] (commands: `node`, `npm`, and `npx`)
  ** {url-nvm}[nvm] (optional, but strongly recommended)
-* {url-gulp}[Gulp CLI] (command: `gulp`)
+* {url-gulp}[Gulp CLI] (command: `gulp`) (can be accessed via `npx gulp`)
 
 You also need {url-git}[git] (command: `git`) to pull down the project and push updates to it.
 
@@ -47,10 +47,16 @@ Once you have Node.js installed, you can proceed with installing the Gulp CLI.
 
 == Gulp CLI
 
-Next, you'll need the Gulp CLI (aka wrapper).
+Next, you may choose to install the Gulp CLI globally.
 This package provides the `gulp` command which 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:
+You can 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-cli
+ $ npm i -g gulp-cli
+
+Alternately, you can run the `gulp` command using `npx` once you've installed the project dependencies, thus waiving the requirement to install it globally.
+
+ $ npx gulp
+
+Using `npx gulp` is the preferred way to invoke the `gulp` command.
 
 Now that you have Node.js and Gulp installed, you're ready to set up the project.

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

@@ -23,24 +23,29 @@ That's the job of npm.
 
 In your terminal, execute the following command (while inside the project folder):
 
- $ npm install
+ $ npm i
 
-This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.
+The `npm i` command, short for `npm install`, installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.
 This folder does not get included in the UI bundle.
 The folder is safe to delete, though npm does a great job of managing it.
 
 You'll notice another file which seems to be relevant here, [.path]_package-lock.json_.
 npm uses this file to determine which concrete version of a dependency to use, since versions in [.path]_package.json_ are typically just a range.
 The information in this file makes the build reproducible across different machines and runs.
 
-If a new dependency must be resolved that isn't yet listed in [.path]_package-lock.json_, npm will update this file with the new information when you run `npm install`.
+Installing the dependencies makes the `npx gulp` command available.
+You can verify this by querying the Gulp version:
+
+ $ npx gulp -v
+
+If a new dependency must be resolved that isn't yet listed in [.path]_package-lock.json_, npm will update this file with the new information when you run `npm i`.
 Therefore, you're advised to commit the [.path]_package-lock.json_ file into the repository whenever it changes.
 
 == Supported build tasks
 
 Now that the dependencies are installed, you should be able to run the `gulp` command to find out what tasks the build supports:
 
- $ gulp --tasks-simple
+ $ npx gulp --tasks-simple
 
 You should see:
 

docs/modules/ROOT/pages/template-customization.adoc

@@ -1,10 +1,72 @@
 = Template Customization
 
 The default UI bundle can be customized using AsciiDoc attributes.
-xref:templates.adoc[] explained how to access such attributes.
-But what are the attributes that actually affect this particular template?
+xref:templates.adoc[] explains how to access such attributes.
+But what are the attributes that actually used by the templates.
 If you're going to use the default UI bundle for your project, you'll want to know.
 
+== page-role attribute
+
+The `page-role` attribute is typically defined per-page.
+This attribute is used to add one or more space-separated classes to the `<body>` tag of that page.
+
+A common use of the `page-role` attribute is to label the home page.
+
+[,asciidoc]
+----
+= Home
+:page-role: home
+
+This is the home page.
+----
+
+////
+Alternately, the role can be set on the document itself.
+
+[,asciidoc]
+----
+[.home]
+= Home
+
+This is the home page.
+----
+////
+
+The resulting HTML will include the following `<body>` start tag:
+
+[,html]
+----
+<body class="article -toc">
+----
+
+The stylesheet can now take advantage of this identity to assign styles to pages that have a given role.
+For example, the home page often requires a different appearance.
+Being able to target that page with CSS allows UI developers to apply that customization.
+
+Note that the UI templates could make use of the page role in other ways.
+The default UI currently only appends the value to the `class` attribute on the `<body>` tag.
+
+=== Hide the TOC sidebar
+
+The one reserved page role that the default UI recognizes is `-toc`.
+This role instructs the site script to remove (i.e., hide) the TOC sidebar.
+Here's how to set it.
+
+[,asciidoc]
+----
+= Page Title
+:page-role: -toc
+
+The TOC sidebar is not displayed even though this page has sections.
+
+== First Section
+
+== Second Section
+----
+
+The AsciiDoc `toc` attribute controls whether the TOC is rendered in the *body* of the article.
+Since the default UI provides an alternate TOC, you most likely don't want to activate the built-in TOC functionality in AsciiDoc when using Antora.
+
 == page-pagination attribute
 
 The `page-pagination` attribute is set in your xref:antora:playbook:asciidoc-attributes.adoc[playbook] in order to enable pagination, if your UI bundle supports it.

gulpfile.js

@@ -18,7 +18,7 @@ const task = require('./gulp.d/tasks')
 const glob = {
   all: [srcDir, previewSrcDir],
   css: `${srcDir}/css/**/*.css`,
-  js: ['gulpfile.js', 'gulp.d/**/*.js', `${srcDir}/{helpers,js}/**/*.js`],
+  js: ['gulpfile.js', 'gulp.d/**/*.js', `${srcDir}/helpers/*.js`, `${srcDir}/js/**/+([^.])?(.bundle).js`],
 }
 
 const cleanTask = createTask({

preview-src/index.adoc

@@ -4,6 +4,7 @@ Author Name
 :idseparator: -
 :!example-caption:
 :!table-caption:
+//:page-role: -toc
 :page-pagination:
 
 [.float-group]
@@ -28,6 +29,7 @@ Nominavi luptatum eos, an vim hinc philosophia intellegebat.
 Lorem pertinacia `expetenda` et nec, [.underline]#wisi# illud [.line-through]#sonet# qui ea.
 H~2~0.
 E = mc^2^.
+*Alphabet* *алфавит* _алфавит_ *_алфавит_*.
 Eum an doctus <<liber-recusabo,maiestatis efficiantur>>.
 Eu mea inani iriure.footnote:[Quisque porta facilisis tortor, vitae bibendum velit fringilla vitae! Lorem ipsum dolor sit amet, consectetur adipiscing elit.]
 
@@ -297,13 +299,19 @@ Eu mea inani iriure.
 [discrete]
 == Voluptua singulis
 
+[discrete]
+=== Nominavi luptatum
+
 Cum dicat putant ne.
 Est in reque homero principes, meis deleniti mediocrem ad has.
 Ex nam suas nemore dignissim, vel apeirian democritum et.
 
 .Antora is a multi-repo documentation site generator
 image::multirepo-ssg.svg[Multirepo SSG,3000,opts=interactive]
 
+.Let's see that again, but a little smaller
+image::multirepo-ssg.svg[Multirepo SSG,300,role=text-left]
+
 Make the switch today!
 
 .Full Circle with Jake Blauvelt