diff options
Diffstat (limited to 'docs/modules/ROOT/pages/index.adoc')
| -rw-r--r-- | docs/modules/ROOT/pages/index.adoc | 59 |
1 files changed, 28 insertions, 31 deletions
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index cf6794d..359fc24 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,17 +1,12 @@ = Antora Default UI // Settings: -:toc: -:toc-title: Contents :idprefix: :idseparator: - :experimental: :hide-uri-scheme: -ifndef::env-github[:icons: font] -ifdef::env-github[] -:important-caption: :exclamation: -endif::[] // URIs: -:uri-project: https://gitlab.com/antora/antora-ui-default +:uri-antora: https://antora.org +:uri-repo: https://gitlab.com/antora/antora-ui-default :uri-preview: https://antora.gitlab.io/antora-ui-default :uri-hbs: http://handlebarsjs.com :uri-gulp: http://gulpjs.com @@ -23,12 +18,11 @@ endif::[] :uri-git: https://git-scm.com :uri-git-dl: {uri-git}/downloads - -This {uri-project}[project] produces the {uri-preview}[default Antora UI bundle] for a documentation site. -It contains the UI assets (page templates, CSS, JavaScript, etc.) and a build script. +This project produces the {uri-preview}[default UI bundle] for documentation sites generated with {uri-antora}[Antora]. +It contains the UI assets (page templates, CSS, JavaScript, images, etc.) and a Gulp build script. The build can be used to preview the UI locally (featuring live updates), or package it for consumption by the site generator. -This documentation explains how to use this project to set up, customize and manage a UI for a documentation site generated by the Antora pipeline. +This documentation explains how to use this project to set up, customize and manage a UI for a documentation site generated with Antora. After reading it, you'll be able to: * [x] Understand how an Antora UI project is structured. @@ -41,20 +35,19 @@ After reading it, you'll be able to: The Antora UI consists of the following file types that are used to structure and style the documentation site pages generated by Antora. -* Handlebars "`page`" templates (layouts and partials) +* Handlebars "`page`" templates (layouts, partials, and helpers) * CSS (enhanced using PostCSS) * JavaScript (UI scripts) * Images / Graphics (specific to the UI) * Fonts -* HTML (sample content for previewing the UI) -* UI model (sample data for previewing the UI) +* Sample content for previewing the UI (HTML and UI model) To understand how the UI works, let's begin by surveying the primary technologies used by the UI. Handlebars (file extension: `.hbs`):: {uri-hbs}[Handlebars] is a "`logic-less`" templating engine used to create HTML from template files. -Templates contain placeholders (i.e., mustache expressions) into which content is injected from a model. -They also accommodate simple logic expressions for repeating content or including it conditionally. +Templates contain placeholders (i.e., mustache expressions like `+{{{page.title}}}+`) into which content is injected from a model. +They also accommodate simple logic expressions for repeating content or including it conditionally (e.g., `+{{#each navigation}}+`) as well as partials (e.g., `+{{> header}}+`). Gulp (script file: [.path]_gulpfile.js_):: {uri-gulp}[Gulp] is a build tool for JavaScript projects. @@ -62,7 +55,7 @@ It configures a collection of tasks that can be used to perform automated tasks Yarn (command: `yarn`):: {uri-yarn}[Yarn] manages software packages (i.e., software dependencies) that it downloads from {uri-npm}. -The software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages. +Software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages. (While npm itself is often used to install Yarn, we do not use npm for any other purpose). package.json::: @@ -78,7 +71,7 @@ A local cache of resolved dependencies that Yarn (or npm) fetches. PostCSS:: This project does not use a CSS preprocessor such as Sass or LESS. Instead, it relies on normal CSS which is enhanced by a series of postprocessors. -The most common postprocessor backports newer CSS features to older browsers by injecting properties with vendor prefixes. +The most common postprocessor backports newer CSS features to older browsers by adding properties with vendor prefixes. == UI project versus UI bundle @@ -103,14 +96,16 @@ package.json yarn.lock src/ css/ - article.css - footer.css + base.css + breadcrumbs.css ... helpers/ and.js + eq.js ... img/ - chevron.svg + back.svg + caret.svg ... layouts/ default.hbs @@ -121,6 +116,7 @@ src/ ... js/ 01-navigation.js + 02-fragment-jumper.js ... vendor/ highlight.js @@ -145,8 +141,8 @@ A Gulp build is used to compile and assemble the UI project files into a UI bund The UI bundle--a distributable archive--provides files which are ready to be used by Antora. -When the UI project files are built by Gulp, they are assembled under the [.path]_build/preview-site/../_ directory. -Since the [.path]_build_ directory is generated, it's safe to remove. +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. This is the content that is used by Antora. @@ -159,9 +155,11 @@ font/ ... helpers/ and.js + eq.js ... img/ - chevron.svg + back.svg + caret.svg ... layouts/ default.hbs @@ -179,24 +177,23 @@ js/ Some of these files have been compiled or aggregated, such as the stylesheets and JavaScript. The benefit of building the UI files is that the files can be optimized for static inclusion in the site without that optimization getting in the way of UI development. For example, the UI build can optimize SVGs or add vendor prefixes to the CSS. -Since this optimization is only applied to the pre-compiled files, it doesn't interfere with the web developer's workflow. +Since these optimizations are only applied to the pre-compiled files, they don't interfere with the web developer's workflow. -== UI compilation and pipeline consumption overview +== UI compilation and generator consumption overview The purpose of an Antora UI project is to get the UI files into a state that Antora can use and to make it reusable. 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. +When handed off to the Antora generator 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. -// These two states (source and pre-compiled) are explained in more detail in the next two sections. The responsibility of compiling the UI is shared between a UI project and Antora. The UI project uses a local build to pre-compile (interpret, consolidate, and/or minimize) the files. -The pre-compiled files are agnostic to Antora's content model, relieving the pipeline from having to deal with this part. +The pre-compiled files are agnostic to Antora's content model, relieving the generator from having to deal with this part. It also allows the UI to be reused. -The UI project build then packages the UI into a bundle, which Antora consumes. -Antora grabs the bundle (which is managed by the `ui-loader` pipeline package), extracts it, and takes compilation to completion by weaving the content model into the Handlebars templates to make the pages and auxiliary data files. +The UI project build then packages the UI into a bundle, which the UI Loader in Antora consumes. +Antora grabs the bundle, extracts it into a UI catalog, and finally takes compilation to completion by weaving the content model into the Handlebars templates to make the pages and auxiliary data files. Antora then copies the remaining UI assets to the site output. Now that you have a general idea of the files that make up the UI and how it gets assembled, let's go over how to set up the project, build the UI, and preview it. |