== Authors
-Development of Antora is lead and sponsored by OpenDevise Inc.
+Development of Antora is led and sponsored by OpenDevise Inc.
--- /dev/null
+name: antora-ui-default
+title: Antora UI
+version: master
+nav:
+- modules/ROOT/nav.adoc
--- /dev/null
+:attachmentsdir: {moduledir}/assets/attachments
+:examplesdir: {moduledir}/examples
+:imagesdir: {moduledir}/assets/images
+:partialsdir: {moduledir}/pages/_partials
--- /dev/null
+.xref:index.adoc[Antora UI]
+* xref:development-workflow.adoc[UI Development Best Practices]
+* xref:install-development-prerequisites.adoc[Install Development Prerequisites]
+* xref:set-up-existing-project.adoc[Set up an Existing UI Project]
+* xref:templates.adoc[Work with the Handlebars Templates]
+* xref:stylesheets.adoc[Work the CSS Stylesheets]
+* xref:build-local-project.adoc[Build a UI Project for Local Preview]
--- /dev/null
+:moduledir: ..
+include::{moduledir}/_attributes.adoc[]
--- /dev/null
+= Build a UI Project for Local Previewing
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+:experimental:
+
+== Build Preview Site
+
+Once you've modified the site UI, the first thing you'll want to do is check out how it looks.
+That's what the files in the [.path]_preview-site/_ folder are for.
+This folder contains HTML file fragments that provide a representative sample of content from the site (saving you from having to generate the whole site just to test the UI).
+These files should give you an idea of how the UI will look when applied to the actual site.
+
+The pages in the preview site are assembled using the Handlebars templates and link to the pre-compiled asset files (emulating the behavior of the site generator).
+Thus, to look at then, you need to run them through the UI build.
+
+There are two preview modes available.
+You can run the build once and examine the result or you can run the build continuously so you can see changes as you make them.
+The next two sections explain how to use these modes.
+
+=== Build Once
+
+To build the UI once for preview, then stop, execute the `build-preview` task using the following command:
+
+ $ gulp build:preview
+
+This task pre-compiles the UI files into the [.path]_build/preview-site/./_ directory.
+To view the preview pages, navigate to the HTML pages in the [.path]_build_ directory using your browser (e.g., [.path]_build/index.html_).
+
+=== Build Continuously
+
+To avoid the need to run the `build-preview` task over and over, you can use the `preview` command instead to have it run continuously.
+This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`").
+
+To launch the preview server, execute the following command:
+
+ $ gulp preview
+
+You'll see two URLs listed in the output of this command:
+
+....
+[BS] Access URLs:
+ ----------------------------------
+ Local: http://localhost:5252
+ External: http://192.168.1.7:5252
+ ----------------------------------
+[BS] Serving files from: build
+[BS] Watching files...
+....
+
+Navigate to the first one to see the preview site.
+While this command is running, any changes you make to the source files will be instantly reflected in the browser.
+This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser.
+
+Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
+
+== Package for Previewing
+
+If you need to package the UI in order to preview the UI on the real site in local development, run the following command:
+
+ $ gulp pack
+
+The `pack` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
+
+The UI bundle will be available at [.path]_build/ui-bundle.zip_.
+You can then point Antora at this bundle using the `--theme-archive` flag.
--- /dev/null
+= UI Development Workflow
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+// This section provides information about some of the UI files you'll be modifying and how to prepare and submit those changes.
+
+All changes pushed to a UI project's master branch can trigger a new release (not described here).
+Therefore, you want to make your changes to a development branch and submit it as a pull request (PR) to be approved.
+(Even better would be to issue the PR from a fork).
+Only when the PR is approved and merged will the new release be triggered.
+
+== git steps
+
+Use the following command to create a local development branch named `name-me`:
+
+ $ git checkout -b name-me -t origin/master
+
+You'll then apply your changes to the UI files.
+Once you're done making changes, commit those changes to the local branch:
+
+ $ git commit -a -m "describe your change"
+
+Then, push your branch to the remote repository:
+
+ $ git push origin name-me
+
+Finally, navigate to your UI project in your browser and create a new pull request from this branch.
+
+The maintainer of the UI should review the changes.
+If the changes are acceptable, the maintainer will merge the pull request.
+As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.
+
+Now that you've got the process down, let's review some of the files you'll be working with in more detail.
--- /dev/null
+= 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.
--- /dev/null
+= Install UI Development Prerequisites
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+// URLs
+:uri-nvm: https://github.com/creationix/nvm
+:uri-node: https://nodejs.org
+:uri-gulp: http://gulpjs.com
+:uri-yarn: https://yarnpkg.com
+:uri-git: https://git-scm.com
+:uri-git-dl: {uri-git}/downloads
+:uri-nvm-install: {uri-nvm}#installation
+// These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not.
+// Did we switch to Node 8 for the UI as well, or is it still 7?
+
+An Antora UI project is based on tools built atop Node.js (aka Node), namely:
+
+* {uri-nvm}[nvm] (optional, but strongly recommended)
+* {uri-node}[Node] (command: `node`)
+* {uri-gulp}[Gulp] (command: `gulp`)
+* {uri-yarn}[Yarn] (command: `yarn`)
+
+You also need {uri-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, {uri-git-dl}[download and install] the git package for your system.
+
+== nvm and Node 8.x
+
+Next, make sure that you have Node 7.8.0 or better installed.
+While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node.
+Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine.
+
+Once you've installed nvm, open a new terminal and install the stable version of Node using the following command:
+
+ $ nvm install node
+
+You can switch to this version of Node at any time using the following command:
+
+ $ nvm use node
+
+Check the version to verify you're on Node 7.8.0 or better.
+
+ $ node --version
+
+== 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
+
+== Yarn
+
+Finally, you will need Yarn, which is the preferred package manager for the Node ecosystem.
+You'll need to use the `npm` command to install Yarn, though this is the last time you'll use the `npm` command.
+You should install Yarn globally (which resolves to a location in your user directory if you're using nvm) using the following command:
+
+ $ npm install -g yarn
+
+Verify Yarn is installed by checking the version:
+
+ $ yarn --version
+
+Now that you have Node, Yarn, and Gulp installed, you're ready to set up the project.
--- /dev/null
+= Set Up an Existing Antora UI Project
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+// URLs
+:uri-project: https://gitlab.com/antora/antora-ui-default
+
+Before you can start working on the UI, you need to grab the sources and initialize the project.
+The sources can be {uri-project}[Antora's default UI] or an existing UI project structured to work with Antora.
+
+== Fetch a UI project
+
+To start, clone the UI project using git:
+
+[subs=attributes+]
+ $ git clone {uri-project} &&
+ cd "`basename $_`"
+
+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 Yarn.
+
+== 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 Yarn.
+
+In your terminal, execute the following command (while inside the project folder):
+
+ $ yarn 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 Yarn does a great job of managing it.
+
+You'll notice another file which seems to be relevant here, [.path]_yarn.lock_.
+Yarn uses this file to determine which specific 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]_yarn.lock_, Yarn will update this file with the new information when you run `yarn install`.
+Therefore, you're advised to commit this 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]
+....
+lint:css
+lint:js
+lint
+format
+build
+build:preview
+preview
+pack
+default
+....
+
+We'll explain what each of these tasks are for and when to use them.
--- /dev/null
+= Work with the CSS Stylesheets
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+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]_stylesheets/article.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.
--- /dev/null
+= Work with the Handlebars Templates
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+
+Antora combines the Handlebars templates with the converted AsciiDoc content to make the pages in the site.
+These "`logic-less`" templates are mostly HTML with some special mustache tags sprinkled in where content is to 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.
+Places in the template where the model is read are enclosed in `{{` and `}}` markers, aka mustaches (e.g., `+{{title}}+`).
+When the `{{` is immediately followed by `>`, that's where the result of a partial is inserted (e.g., `+{{> head }}+`.
+
+=== Template variables
+
+*This model is not final.*
+*Variable names and purposes may change.*
+
+Here's an overview of the available model:
+
+.Variables available to the Handlebars templates
+[#template-variables,cols="1m,3"]
+|===
+| Name | Description
+
+| site
+| Information about the site.
+Properties include url, title, buildNumber, domains, aspect, aspectNav, and swiftypeKey.
+
+| title
+| The page title (also used as the primary heading).
+
+| contents
+| The main article content in HTML format.
+Sourced from AsciiDoc and converted to HTML by the Asciidoctor processor.
+
+| description
+| The text of the description attribute in the AsciiDoc header, if specified.
+
+| keywords
+| A comma-separated list of keywords defined in the AsciiDoc header, if specified.
+
+| domain
+| Information about the navigation domain of the current page.
+Properties include name, title, type, versioned, version, versions, url, root, and siteAspect.
+
+| versions
+| All versions of the current page, including the current page.
+Each entry has the properties url, string, and missing.
+
+| breadcrumbs
+| An array of breadcrumb items that represent the current selection in the navigation tree.
+
+| uiRootPath
+| The path to the root directory of the UI.
+
+| canonicalUrl
+| The canonical URL for the current page.
+If there are older versions of the page, the canonical URL is the URL of the latest version.
+If this is an aspect page, the canonical URL is the URL of the primary (non-aspect) page.
+
+| editUrl
+| The URL to edit the current page, typically on GitHub.
+
+| siteRootUrl
+| The URL of the site root relative to the current page.
+If the site does not have a root component, this value is null.
+
+| home
+| Indicates whether the current page is the home page of the site.
+
+| navigation
+| A collection of navigation links for the current page.
+Each navigation item contains the property `text` as well as the optional properties `href` and (child) `items`.
+|===
+
+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]
+----
+<meta class="swiftype" name="title" data-type="string" content="{{title}}">
+----
+
+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 <<template-variables>>.
+
+Save the file, commit it to git, push the branch, and allow the approval workflow to play out.
projects / eg-antora.git / commitdiff