Optional Title
-
-
-This is a paragraph in a sidebar.
-| - - | -
-
-
-Watch out! - |
-
)
-
-How xref:antora:asciidoc:monospace.adoc[inline monospace text] is displayed depends on the fixed-width font loaded by your UI and the CSS styles it applies to the `` HTML tag.
-
-[source,html]
-----
-A monospace word, or a monospace phrase of text.
-----
-
-Since `` is a semantic HTML element, it automatically inherits default styling (`font-family: monospace`) from the browser.
-If you want to override the browser styles, you'll need to define properties on the `code` selector in the stylesheet for your UI.
-
-In the default UI, the `code` element is styled using the fixed-width font loaded by the stylesheet (Roboto Mono).
-For example:
-
-[example]
-A monospace `word`, or a monospace `phrase of text`.
-
-[#highlight]
-== Highlighted text ()
-
-How xref:antora:asciidoc:highlight.adoc[highlighted (or marked) text] appears on your site depends on the CSS styles the UI applies to the `` HTML tag.
-
-[source,html]
-----
-Let’s add some highlight to it.
-----
-
-Since `` is a semantic HTML element, it automatically inherits default styling (`background-color: yellow`) from the browser.
-Here's an example:
-
-[example]
-Let's add some #highlight# to it.
-
-If you want to override the browser styles, you'll need to define properties on the `mark` selector in the stylesheet for your UI.
diff --git a/docs/modules/ROOT/pages/list-styles.adoc b/docs/modules/ROOT/pages/list-styles.adoc
deleted file mode 100644
index 5fff9c79..00000000
--- a/docs/modules/ROOT/pages/list-styles.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-= List Styles
-
-== Ordered list numeration
-
-The browser automatically numbers xref:antora:asciidoc:ordered-and-unordered-lists.adoc[ordered lists] and selects a numeration style by list depth in the following order: decimal, lower-alpha, lower-roman, upper-alpha, upper-roman.
-
-AsciiDoc allows the author to override the numeration style for an ordered list.
-Here's an example of that output:
-
-[source,html]
-----
-
-
-a
b
c
-
-----
-
-In order to support this customization, you must assign the list-style-type property to the following classes on the `` element in your stylesheet.
-
-|===
-| class |list-style-type property value
-
-|arabic
-|decimal
-
-|decimal
-|decimal-leading-zero
-
-|loweralpha
-|lower-alpha
-
-|lowergreek
-|lower-greek
-
-|lowerroman
-|lower-roman
-
-|upperalpha
-|upper-alpha
-
-|upperroman
-|upper-roman
-|===
-
-== Checklist
-
-A xref:antora:asciidoc:checklists.adoc[checklist] is an unordered list with items that are prefixed with a checkbox marker (checked or unchecked).
-Here's an AsciiDoc source example that produces a checklist:
-
-[source,asciidoc]
-----
-* [ ] todo
-* [x] done!
-----
-
-If font-based icons are enabled (`icons=font`), the checkbox gets inserted as the first element of the paragraph element that contains the list item text.
-
-[source,html]
-----
-
-
--
-
todo
-
--
-
done!
-
-
-
-----
-
-The recommended approach is to hide the list markers (`list-style: none`), then add a checkbox glyph on the icon element using either a background image or a `before` pseudo element.
-
-Here's how it might appear:
-
-* [ ] todo
-* [*] done!
diff --git a/docs/modules/ROOT/pages/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc
deleted file mode 100644
index 0b6571bd..00000000
--- a/docs/modules/ROOT/pages/prerequisites.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= UI Development Prerequisites
-// URLs:
-:url-nvm: https://github.com/creationix/nvm
-:url-node: https://nodejs.org
-:url-gulp: http://gulpjs.com
-:url-git: https://git-scm.com
-:url-git-dl: {url-git}/downloads
-:url-node-releases: https://nodejs.org/en/about/releases/
-// These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not.
-
-An Antora UI project is based on tools built atop Node.js, namely:
-
-* {url-node}[Node.js] (commands: `node` and `npm`)
- ** {url-nvm}[nvm] (optional, but strongly recommended)
-* {url-gulp}[Gulp CLI] (command: `gulp`)
-
-You also need {url-git}[git] (command: `git`) to pull down the project and push updates to it.
-
-== git
-
-First, make sure you have git installed.
-
- $ git --version
-
-If not, {url-git-dl}[download and install] the git package for your system.
-
-== Node.js
-
-You need Node.js installed on your machine to use Antora, including the default UI.
-Antora follows the Node.js release schedule, so we advise that you choose an active long term support (LTS) release of Node.js.
-We recommend using the latest active Node.js LTS version.
-While you can use other versions of Node.js, Antora is only tested against LTS releases.
-
-To check whether you have Node.js installed, and which version, open a terminal and type:
-
- $ node --version
-
-You should see a version string, such as:
-
- v10.15.3
-
-If the command fails with an error, it means you don't have Node.js installed.
-The best way to install Node.js is to use nvm (Node Version Manager).
-Refer to xref:antora:install:linux-requirements.adoc#install-nvm[Install nvm and Node.js (Linux)], xref:antora:install:macos-requirements.adoc#install-nvm[Install nvm and Node.js (macOS)], or xref:antora:install:windows-requirements.adoc#install-nvm[Install nvm and Node.js (Windows)] for instructions.
-
-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).
-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:
-
- $ npm install -g gulp-cli
-
-Now that you have Node.js and Gulp installed, you're ready to set up the project.
diff --git a/docs/modules/ROOT/pages/set-up-project.adoc b/docs/modules/ROOT/pages/set-up-project.adoc
deleted file mode 100644
index 9dad8aa5..00000000
--- a/docs/modules/ROOT/pages/set-up-project.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= Set up a UI Project
-:url-project: https://gitlab.com/antora/antora-ui-default.git
-
-Before you can start working on the UI, you need to grab the sources and initialize the project.
-The sources can be {url-project}[Antora's default UI] or an existing UI project structured to work with Antora.
-
-== Fetch the Default UI project
-
-To start, clone the default UI project using git:
-
-[subs=attributes+]
- $ 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.
-
-== Install dependencies
-
-Next, you'll need to initialize the project.
-Initializing the project essentially means downloading and installing the dependencies into the project.
-That's the job of npm.
-
-In your terminal, execute the following command (while inside the project folder):
-
- $ npm install
-
-This command 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`.
-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
-
-You should see:
-
-[.output]
-....
-default
-clean
-lint
-format
-build
-bundle
-bundle:pack
-preview
-preview:build
-....
-
-We'll explain what each of these tasks are for and when to use them.
diff --git a/docs/modules/ROOT/pages/sidebar-styles.adoc b/docs/modules/ROOT/pages/sidebar-styles.adoc
deleted file mode 100644
index 9ce0ca64..00000000
--- a/docs/modules/ROOT/pages/sidebar-styles.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-= Sidebar Styles
-
-This page describes the in-page sidebar block styles, not the styles for the navigation sidebar.
-
-== Sidebar blocks
-
-xref:antora:asciidoc:sidebar.adoc[Sidebars] can contain any type of content.
-The sidebar title is specified by the block class title.
-Here's an AsciiDoc source example that produces a sidebar with a title:
-
-[source,asciidoc]
-----
-.Optional Title
-****
-This is a paragraph in a sidebar.
-****
-----
-
-[source,html]
-----
-
-----
diff --git a/docs/modules/ROOT/pages/style-guide.adoc b/docs/modules/ROOT/pages/style-guide.adoc
deleted file mode 100644
index d23ff602..00000000
--- a/docs/modules/ROOT/pages/style-guide.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-= UI Element Style Guide
-
-When creating a UI theme for Antora, there are certain elements in the UI that require support from the CSS to work correctly.
-This list includes elements in the shell (i.e., frame) and in the document content.
-This document identifies these UI elements.
-
-//== UI Shell
-
-// TODO
-
-== Document Content
-
-The HTML in the main content area is generated from AsciiDoc using Asciidoctor.
-AsciiDoc has numerous content elements that require assistance from CSS to render properly.
-
-These elements include:
-
-* xref:inline-text-styles.adoc[Inline text emphasis]
-* xref:admonition-styles.adoc[Admonitions]
-* xref:list-styles.adoc[Lists]
-* xref:sidebar-styles.adoc[Sidebars]
-* xref:ui-macro-styles.adoc[Button, keybinding, and menu UI macros]
diff --git a/docs/modules/ROOT/pages/stylesheets.adoc b/docs/modules/ROOT/pages/stylesheets.adoc
deleted file mode 100644
index aff53168..00000000
--- a/docs/modules/ROOT/pages/stylesheets.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-= Work with the CSS Stylesheets
-
-The stylesheets are written in CSS.
-These stylesheets utilize CSS variables to keep the CSS DRY and easy to customize.
-
-== Stylesheet organization and processing
-
-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.
-
-== Add a new CSS rule
-
-Let's consider the case when you want to modify the font size of a section title.
-
-First, make sure you have set up the project and created a development branch.
-Next, open the file [.path]_src/css/doc.css_ and modify the rule for the section title.
-
-[source,css]
-----
-.doc h1 {
- font-size: 2.5rem;
- margin-bottom: 1rem;
- margin-top: 2rem
-}
-----
-
-Save the file, commit it to git, push the branch, and allow the approval workflow to play out.
diff --git a/docs/modules/ROOT/pages/templates.adoc b/docs/modules/ROOT/pages/templates.adoc
deleted file mode 100644
index 39a259b6..00000000
--- a/docs/modules/ROOT/pages/templates.adoc
+++ /dev/null
@@ -1,201 +0,0 @@
-= Work with the Handlebars Templates
-
-Antora combines the Handlebars templates with the converted AsciiDoc content and other UI model data to make the pages in the site.
-These "`logic-less`" templates are mostly HTML with some special mustache tags sprinkled in where content should be inserted.
-
-== What do the templates do?
-
-The layout templates, which are stored in [.path]_src/layouts/_, provide the main page structure.
-The partial templates, in [.path]_src/partials/_, fill in different regions of a page, such as the navigation and footer.
-
-The templates read from a model that's populated by Antora.
-The model can be accessed by enclosing path expressions in mustaches, which are `{{` and `}}` or `{{{` and `}}}` (e.g., `+{{{page.title}}}+`).
-The double mustaches escape the value for HTML, whereas triple mustaches insert the value as is.
-
-WARNING: If the mustaches are preceded by a backslash (e.g, `\{{`), the expression will be disabled.
-This often comes up when constructing URLs.
-To avoid this problem, you should use forward slashes in URLs instead of backslashes.
-
-When `{{` is immediately followed by `>`, that invokes a partial (from the partials directory) and inserts the result (e.g., `+{{> head}}+`.
-In other words, that's not a model reference like the other mustache expressions.
-
-=== Template variables
-
-CAUTION: This model is not final.
-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"]
-|===
-| Name | Description
-
-s| [[site]]site
-| Information about the site.
-
-| site.url
-| The base URL of the site, if specified in the playbook.
-
-| site.path
-| The pathname (i.e., subpath) of the site.url under which the site is hosted (e.g., /docs).
-This value is empty if site.url is not defined, has no path segment, or matches /.
-Can be removed from the site.url value using a helper (e.g., `deleteSuffix site.url site.path`)
-(since Antora 2.1)
-
-| site.title
-| The title 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.
-Properties of each version include name (since 2.3), version, displayVersion, prerelease (if set), title, url, asciidoc (since 2.3), and navigation.
-The navigation property on each version provides access to the navigation menu for that component version.
-
-| site.ui
-| Information about the site UI.
-
-| site.ui.defaultLayout
-| The default page layout used for this site.
-
-| site.ui.url
-| The absolute base URL of the UI.
-
-s| [[page]]page
-| Information about the current page.
-
-| page.title
-| The page title in HTML format (often used as the primary heading).
-This value may include inline HTML elements and XML character references.
-
-| page.contents
-| The main article content in HTML format.
-Sourced from AsciiDoc and converted to HTML by the Asciidoctor processor.
-
-| page.attributes
-| Any AsciiDoc document attribute prefixed with `page-`.
-The `page-` prefix is dropped from the name used in this model.
-For example, the value of the document attribute named `page-support-phone` can be accessed via the UI model using `page.attributes.support-phone`.
-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.description
-| The text of the description attribute in the AsciiDoc header, if specified.
-
-| page.keywords
-| A comma-separated list of keywords defined in the AsciiDoc header, if specified.
-
-| page.component
-| Information about the component for the current page.
-Properties include name, title, url, latest, and versions.
-
-| page.componentVersion
-| Information about the component version for the current page.
-Properties include name (since 2.3), version, displayVersion, prerelease (if set), title, url, and asciidoc (since 2.3).
-
-| page.module
-| The name of the module for the current page.
-
-| page.relativeSrcPath
-| The path of the current page relative to the pages directory in the current module (since 2.3).
-
-| page.version
-| The name of the version for the current page.
-
-| page.displayVersion
-| The name of the display version for the current page.
-
-| page.versions
-| All versions of the current page, including the current page.
-Each entry has the properties url, string, and missing.
-
-| page.latest
-| The entry from `page.versions` that corresponds to the latest version available of this page.
-The latest page may not come from the latest version of the component (if the page is missing in that version).
-This property is not set if this page is in a versionless component.
-
-| page.breadcrumbs
-| An array of breadcrumb items that represent the current selection in the navigation tree.
-Includes text-only and external items.
-
-| page.navigation
-| The hierarchical navigation menu for the component version of the current page.
-Each navigation item contains the property `content` as well as the optional properties `url` and (child) `items`.
-
-| page.url
-| The URL for the current page.
-This value is a root-relative path.
-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).
-If there's only a single version of the component, the canonical URL is the qualified URL of the current page.
-
-| page.editUrl
-| The URL to edit the current page (i.e., activates the web-based editor on the git host).
-This value is derived automatically for the hosts github.com, gitlab.com, pagure.io, and bitbucket.org, even if the repository is private.
-If the host is not recognized, or you want to customize the value, you can use the `edit_url` key on the content source in the playbook.
-
-The default UI shows an "Edit this Page" link that points to this URL unless the repository is private (i.e., `page.origin.private` is true) or `page.fileUri` is set.
-You can force this link to be shown by setting the environment variable `FORCE_SHOW_EDIT_PAGE_LINK` (e.g., `FORCE_SHOW_EDIT_PAGE_LINK=true`) or by customizing the logic in the UI template.
-
-| page.fileUri
-| The local file:// URI to edit the current page if the page originates from the local filesystem (i.e., the worktree).
-
-If this property is set, the default UI shows an "Edit this Page" link that points to this URI (instead of the `page.editUrl` value) unless the `CI` environment variable is set (e.g., `CI=true`).
-When the `CI` environment variable is set, the default UI ignores this property (since linking to a local file:// URI in a published site doesn't make any sense).
-
-| page.origin.private
-| This value will be true if the repository requires authentication or the repository URL embeds credentials.
-In the default UI, if this value is `true`, the "Edit this Page" link is disabled.
-A quick way to force this property to be `true` (even if the repository is public) is to begin the content source URL in the playbook with empty credentials, as in `\https://@`.
-Then, the "Edit the Page" link will not appear.
-
-| page.home
-| Indicates whether the current page is the start (aka home) page of the site.
-
-| page.layout
-| The page layout for the current page.
-
-| page.next
-| The next reachable page in the navigation tree (skips past text-only and external items).
-
-| page.previous
-| The previous reachable page in the navigation tree (skips past text-only and external items).
-
-| page.parent
-| The parent page in the navigation tree (skips past text-only and external items).
-
-s| env
-| The map of environment variables (sourced from `process.env`).
-
-s| siteRootPath
-| The relative path to the root of the published site.
-
-s| uiRootPath
-| The relative path to the root directory of the UI.
-
-s| antoraVersion
-| The version of Antora used to build the site (specifically the version of the @antora/page-composer package).
-|===
-
-This model is likely to grow over time.
-
-== Modify a template
-
-Let's consider the case when you want to add a new meta tag inside the HTML head.
-
-First, make sure you have set up the project and created a development branch.
-Next, open the file [.path]_templates/partials/head.hbs_ and add your tag.
-
-[source,html]
-----
-
-----
-
-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 <>.
-
-Save the file, commit it to git, push the branch, and allow the approval workflow to play out.
diff --git a/docs/modules/ROOT/pages/ui-macro-styles.adoc b/docs/modules/ROOT/pages/ui-macro-styles.adoc
deleted file mode 100644
index 8a58017d..00000000
--- a/docs/modules/ROOT/pages/ui-macro-styles.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= UI Macro Styles
-
-Asciidoctor supports xref:antora:asciidoc:ui-macros.adoc[three UI element representations] out of the box, which are made from corresponding inline UI macros.
-
-* button (btn macro)
-* keybinding (kbd macro)
-* menu (menu macro)
-
-The UI elements are output using semantic HTML elements, so they inherit some default styling from the browser.
-However, to look proper, they require some additional styling.
-
-== Button
-
-A xref:antora:asciidoc:ui-macros.adoc#button[button] is meant to represent an on-screen button (`+btn:[Save]+`).
-However, it should not appear like an actual button as that could confuse the reader into thinking it's interactive.
-Therefore, a button is rendered as a bold text by default:
-
-[source,html]
-----
-Save
-----
-
-Traditionally, a button reference is styled by surrounding the text with square brackets, as shown here:
-
-btn:[Save]
-
-== Keybinding
-
-A xref:antora:asciidoc:ui-macros.adoc#keybinding[keybinding] can be a single key (`+kbd:[F11]+`) or a sequence of keys (`+kbd:[Ctrl+F]`).
-Here's the HTML that's generated for these two forms.
-
-[source,html]
-----
-F11
-Ctrl+F
-----
-
-Here's how these might appear:
-
-[%hardbreaks]
-kbd:[F11]
-kbd:[Ctrl+F]
-
-== Menu
-
-A xref:antora:asciidoc:ui-macros.adoc#menu[menu] can be a top-level menu reference (`+menu:File[]+`) or a nested selection (`+menu:File[Save]+`).
-Here's the HTML that's generated for these two forms.
-
-[source,html]
-----
-File
-
-----
-
-This might be rendered as:
-
-menu:File[]
-
-menu:File[Save]
-
-The default styling applied to a menu reference is usually sufficient.