diff options
Diffstat (limited to 'docs/modules/ROOT/pages/index.adoc')
-rw-r--r-- | docs/modules/ROOT/pages/index.adoc | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..cf6794d --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,202 @@ += 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-preview: https://antora.gitlab.io/antora-ui-default +:uri-hbs: http://handlebarsjs.com +:uri-gulp: http://gulpjs.com +:uri-yarn: https://yarnpkg.com +:uri-npm: https://npmjs.com +:uri-node: https://nodejs.org +:uri-nvm: https://github.com/creationix/nvm +:uri-nvm-install: {uri-nvm}#installation +: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. +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. +After reading it, you'll be able to: + +* [x] Understand how an Antora UI project is structured. +* [x] Set up your environment to work on the UI project. +* [x] Launch a preview server to visually inspect the UI. +* [x] Adopt a development workflow to share and accept changes to the UI. +* [x] Package a UI for your documentation site that Antora can use. + +== File type and technology overview + +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) +* 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) + +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. + +Gulp (script file: [.path]_gulpfile.js_):: +{uri-gulp}[Gulp] is a build tool for JavaScript projects. +It configures a collection of tasks that can be used to perform automated tasks such as compiling files, running a preview server, or publishing a release. + +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. +(While npm itself is often used to install Yarn, we do not use npm for any other purpose). + +package.json::: +This file keeps track of the dependencies (described using fuzzy versions) that Yarn should fetch. + +yarn.lock::: +This file contains a report of which dependencies Yarn resolved. +This information ensures that the dependency resolution is reproducible. + +node_modules/::: +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. + +== 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. +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) + +You should think of the UI project's master 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: + +[.output] +.... +README.adoc +gulpfile.js +package.json +yarn.lock +src/ + css/ + article.css + footer.css + ... + helpers/ + and.js + ... + img/ + chevron.svg + ... + layouts/ + default.hbs + 404.hbs + partials/ + article.hbs + breadcrumbs.hbs + ... + js/ + 01-navigation.js + ... + vendor/ + highlight.js +preview-site-src/ + index.html + ui-model.yml +tasks/ + lib/ + gulp-prettier-eslint.js + build.js + build-preview.js + format.js + lint-css.js + lint-js.js + pack.js + preview.js +.... + +A Gulp build is used to compile and assemble the UI project files into a UI bundle. + +=== UI bundle structure (releases) + +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. + +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. + +[.output] +.... +css/ + site.css +font/ + ... +helpers/ + and.js + ... +img/ + chevron.svg + ... +layouts/ + default.hbs + 404.hbs +partials/ + article.hbs + breadcrumbs.hbs + ... +js/ + site.js + vendor/ + highlight.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. + +== UI compilation and pipeline 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. +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. +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. +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. |