Commit c8e2e90c authored by Thomas Bouffard's avatar Thomas Bouffard
Browse files

doc: do not store antora-ui-default doc in the repository

The documentation was outdated and was never updated. So remove the AsciiDoc
source file and reference the antora-ui default site instead.

README: fix color declaration for theming. We are not using javascript anymore
parent f18ac41f
......@@ -17,7 +17,7 @@ It is based on the https://gitlab.com/antora/antora-ui-default[Antora Default UI
The project requires Node 16, for nvm user, run `nvm use`.
For more details, see the xref:docs/modules/ROOT/pages/prerequisites.adoc[prerequisites].
For more details, see the https://docs.antora.org/antora-ui-default/prerequisites/[prerequisites].
== Usage
......@@ -27,7 +27,7 @@ Currently, we embed the ui-bundle.zip in the main https://github.com/bonitasoft/
[TIP]
====
Simple flow to 'release' a new version of the theme (i.e use a new version of the UI bundle in the doc site):
Simple flow to 'release' a new version of the theme (i.e. use a new version of the UI bundle in the doc site):
- Build locally this repository (type `gulp bundle` at the root of the repository) -> _build/ui-bundle.zip_ is created +
- Clone the repository https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site], and create a new branch to update the UI bundle
......@@ -37,7 +37,7 @@ Simple flow to 'release' a new version of the theme (i.e use a new version of th
== Development
A static or live preview of the theme is available, see the xref:docs/modules/ROOT/pages/build-preview-ui.adoc[build-preview-ui]
A static or live preview of the theme is available, see the https://docs.antora.org/antora-ui-default/build-preview-ui/[build-preview-ui]
documentation.
To build the bundle to be used in the Antora playbook, run `gulp bundle`.
......@@ -45,13 +45,12 @@ To build the bundle to be used in the Antora playbook, run `gulp bundle`.
=== Change some colors in the UI
If you are only here to update some colors in the UI, it should be easy. +
All used colors are defined in _src/stylsheets/globals.var.scss_ +
At the beggining of the file, you will find the light colors and the dark colors. +
All used colors are defined in _src/stylesheets/globals.var.scss_ +
At the beginning of the file, you will find the light colors and then, the dark colors. +
If you need to add a new color in the color set, then you have to:
- Create a variable `--color-XXX-light` in the light color set
- Create a variable `--color-XXX-dark` in the dark color set
- Add `'--color-XXX'` in the color list at the beggining of the file _src/js/header-01-theme.js_
- Create a variable `--color-XXX` for the light color set in the `:root` selector
- Create the same variable for the dark color set, in the `html[data-theme='dark'] ` selector
- Use this new color by using `var(--color-XXX)` in some css classes
[CAUTION]
......
name: antora-ui-default
title: Antora Default UI
version: master
nav:
- modules/ROOT/nav.adoc
* xref:prerequisites.adoc[UI Development Prerequisites]
* xref:set-up-project.adoc[Set up a UI Project]
* xref:build-preview-ui.adoc[Build and Preview the UI]
* xref:development-workflow.adoc[UI Development Workflow]
* xref:templates.adoc[Work with the Handlebars Templates]
* xref:stylesheets.adoc[Work with the CSS Stylesheets]
** xref:add-fonts.adoc[Add Fonts]
* xref:style-guide.adoc[UI Element Styles]
** xref:inline-text-styles.adoc[Inline Text]
** xref:admonition-styles.adoc[Admonitions]
** xref:list-styles.adoc[Lists]
** xref:sidebar-styles.adoc[Sidebars]
** xref:ui-macro-styles.adoc[UI Macros]
= Add Fonts
This page explains how to add new fonts to your UI.
These instructions assume you've forked the default UI and are able to customize it.
There are three steps involved:
. Add the font to your UI project
. Add a font-face declaration to your stylesheet
. Use the new font in your stylesheet
How you reference the font file in the font-face declaration depends on how you decide to manage it.
You can manage the font with npm or download it manually and add it directly to your UI project.
The following sections describe each approach in turn.
== npm managed
You can use npm (or Yarn) to manage the font.
This approach saves you from having to store the font file directly in your UI project.
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
. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
. In that file, declare the font face:
+
[source,css]
----
@font-face {
font-family: "Open Sans";
font-style: normal;
font-weight: 400;
src:
local("Open Sans"),
local("Open Sans-Regular"),
url(~typeface-open-sans/files/open-sans-latin-400.woff) format("woff")
}
----
+
The Gulp build recognizes the `~` URL prefix and copies the font from the npm package to the build folder (and hence bundle).
+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
+
[source,css]
----
@import "typeface-open-sans.css";
----
. Repeat the previous steps for each font style and weight you want to use from that package.
. Change the CSS to use your newly imported font:
+
[source,css]
----
html {
font-family: "Open Sans", sans;
}
----
+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
. Test the new font by previewing your UI:
$ 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.
== Manual
A simpler approach to adding fonts is to store them directly in your project.
Here are the steps involved.
. Download the font files and add them to the [.path]_src/font_ folder.
Create this folder if it does not exist.
. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
. In that file, declare the font face:
+
[source,css]
----
@font-face {
font-family: "Open Sans";
font-style: normal;
font-weight: 400;
src:
local("Open Sans"),
local("Open Sans-Regular"),
url(../font/open-sans-latin-400.woff) format("woff")
}
----
+
Note that the path is a relative path starting from the [.path]_src/css_ folder to the [.path]_src/font_ folder.
+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
+
[source,css]
----
@import "typeface-open-sans.css";
----
. Repeat the previous steps for each font style and weight you want to use.
. Change the CSS to use your newly imported font:
+
[source,css]
----
html {
font-family: "Open Sans", sans;
}
----
+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
. Test the new font by previewing your UI:
$ 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.
= Admonition Styles
An xref:antora:asciidoc:admonitions.adoc[admonition], also known as a notice, helps draw attention to content with a special label or icon.
== Admonition blocks
An admonition block is a table.
The table title element is specified by the block class: tip, note, important, warning, or caution.
Here's an AsciiDoc source example that produces an admonition with the table title warning:
[source,asciidoc]
----
WARNING: Watch out!
----
If font-based icons are enabled (`icons=font`), the table title text is replaced by the associated icon.
[source,html]
----
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Watch out!</p>
</div>
</td>
</tr>
</table>
</div>
----
Here's how it might appear when the title is displayed as text:
WARNING: Watch out!
= Build a UI Project for Local Preview
// 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-src/_ folder are for.
This folder contains HTML file fragments that provide a representative sample of content from the site.
The preview saves 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 them, 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 following command:
$ 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_).
=== Build Continuously
To avoid the need to run the `preview:build` task over and over while developing, 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 a URL listed in the output of this command:
....
[12:59:28] Starting 'preview:serve'...
[12:59:28] Starting server...
[12:59:28] Server started http://localhost:5252
[12:59:28] Running server
....
Navigate to the URL to view 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 `preview: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 bundle the UI in order to preview the UI on the real site in local development, run the following command:
$ gulp bundle
The `bundle` 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 `--ui-bundle-url` command-line option.
If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:
$ gulp bundle:pack
The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
= UI Development Workflow
// 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.
= Antora Default UI
// Settings:
:idprefix:
:idseparator: -
:experimental:
:hide-uri-scheme:
// URIs:
: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
: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 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 to package it for consumption by the Antora site generator.
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.
* [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, partials, and helpers)
* CSS (enhanced using PostCSS)
* JavaScript (UI scripts)
* Images / Graphics (specific to the UI)
* Fonts
* 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 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/index.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.
npm (command: `npm`)::
npm manages software packages (i.e., software dependencies) that it downloads from {uri-npm}.
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.
package.json:::
This file keeps track of the dependencies (described using fuzzy versions) that npm (or Yarn) should fetch.
package-lock.json:::
This file contains a report of which dependencies npm resolved.
This information ensures that dependency resolution is reproducible.
node_modules/:::
A local cache of resolved dependencies that npm (or Yarn) 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 adding 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/
index.js
lib/
tasks/
package.json
package-lock.json
src/
css/
base.css
breadcrumbs.css
...
helpers/
and.js
eq.js
...
img/
back.svg
caret.svg
...
layouts/
default.hbs
404.hbs
partials/
article.hbs
breadcrumbs.hbs
...
js/
01-navigation.js
02-fragment-jumper.js
...
vendor/
highlight.js
preview-src/
index.html
ui-model.yml
....
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]_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.
[.output]
....
css/
site.css
font/
...
helpers/
and.js
eq.js
...
img/
back.svg
caret.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 these optimizations are only applied to the pre-compiled files, they don't interfere with the web developer's workflow.
== 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.
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.
The responsibility of compiling the UI is shared between a UI project and Antora.
The UI project uses a local build to pre-compile (i.e., interpret, consolidate, and/or minimize) the files.
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 the UI Loader in Antora consumes.
Antora grabs the bundle, extracts it into a UI catalog, and takes compilation to completion by weaving the Antora's 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 an overview 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.
= Inline Text Styles
:example-caption!:
////
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.
////
This page describes how to style text in the contents of the page which is visually emphasized.
[#bold]
== Bold text (<strong>)
How xref:antora:asciidoc:bold.adoc[text marked as bold] appears on your site depends on the fonts loaded by the UI and the CSS styles the UI applies to the `<strong>` HTML tag.
[source,html]
----
A bold <strong>word</strong>, or a bold <strong>phrase of text</strong>.
----
Since `<strong>` is a semantic HTML element, it automatically inherits default styling (`font-weight: bold`) from the browser.
If you want to override the browser styles, you'll need to define properties on the `strong` selector in the stylesheet for your UI.
In the default UI, the `<strong>` element is styled in the 500 font weight of the current typeface (Roboto).
For example:
[example]
A bold *word*, or a bold *phrase of text*.
[#italic]
== Italic text (<em>)
How xref:antora:asciidoc:italic.adoc[italicized text] appears on your site depends on the fonts loaded by the UI and the CSS styles the UI applies to the `<em>` HTML tag.
[source,html]
----
An italic <em>word</em>, or an italic <em>phrase of text</em>.
----
Since `<em>` is a semantic HTML element, it automatically inherits default styling (`font-style: italic`) from the browser.
If you want to override the browser styles, you'll need to define properties on the `em` selector in the stylesheet for your UI.
In the default UI, the `em` element is styled in the italic font variant of the current typeface (Roboto).
For example:
[example]
An italic _word_, or an italic _phrase of text_.
[#monospace]
== Monospace text (<code>)
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 `<code>` HTML tag.
[source,html]
----
A monospace <code>word</code>, or a monospace <code>phrase of text</code>.
----
Since `<code>` 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 (<mark>)
How xref:antora:asciidoc:highlight.adoc[highlighted (or marked) text] appears on your site depends on the CSS styles the UI applies to the `<mark>` HTML tag.
[source,html]
----
Let&#8217;s add some <mark>highlight</mark> to it.
----
Since `<mark>` 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.
= 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]
----
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li><p>a</p></li>
<li><p>b</p></li>
<li><p>c</p></li>
</ol>
</div>
----
In order to support this customization, you must assign the list-style-type property to the following classes on the `<ol>` element in your stylesheet.
|===
|<ol> class |list-style-type property value