Skip to content
Permalink
Browse files
CAMEL-11492: Antora based website build
  • Loading branch information
zregvart committed Dec 12, 2018
1 parent 1586f65 commit 21ce558cc0cbf463b37ed74f6aa02a0ac2533bda
Show file tree
Hide file tree
Showing 97 changed files with 13,727 additions and 0 deletions.
@@ -0,0 +1,4 @@
node_modules
public
static

@@ -0,0 +1,8 @@
FROM antora/antora

ADD . /camel-website

WORKDIR /camel-website

RUN antora site.yml

@@ -0,0 +1,9 @@
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
@@ -0,0 +1,9 @@
{
"extends": "standard",
"rules": {
"arrow-parens": ["error", "always"],
"comma-dangle": ["error", "always-multiline"],
"max-len": [1, 120, 2],
"spaced-comment": "off"
}
}
@@ -0,0 +1,3 @@
/build/
/node_modules/
/public/
@@ -0,0 +1 @@
8
@@ -0,0 +1,6 @@
{
"extends": "stylelint-config-standard",
"rules": {
"comment-empty-line-before": null
}
}

Large diffs are not rendered by default.

@@ -0,0 +1,173 @@
= Antora Default UI
// Settings:
:experimental:
:hide-uri-scheme:
// Project URIs:
:uri-project: https://gitlab.com/antora/antora-ui-default
:uri-preview: https://antora.gitlab.io/antora-ui-default
:uri-ci-pipelines: {uri-project}/pipelines
:img-ci-status: {uri-project}/badges/master/pipeline.svg
// External URIs:
:uri-antora: https://antora.org
:uri-git: https://git-scm.com
:uri-git-dl: {uri-git}/downloads
:uri-gulp: http://gulpjs.com
:uri-opendevise: https://opendevise.com
:uri-node: https://nodejs.org
:uri-nvm: https://github.com/creationix/nvm
:uri-nvm-install: {uri-nvm}#installation
:uri-yarn: https://yarnpkg.com

image:{img-ci-status}[CI Status (GitLab CI), link={uri-ci-pipelines}]

This project is an archetype that demonstrates how to produce a UI bundle for use in a documentation site generated with {uri-antora}[Antora].
You can see a preview of the default UI at {uri-preview}.

== Use the Default UI

If you want to use the default UI for your Antora-generated site, add the following UI configuration to your playbook:

[source,yaml,subs=attributes+]
----
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true
----

Read on to learn how to use your own build of the default UI.

== Quickstart

This section offers a basic tutorial for learning how to preview the default UI and bundle it for use with Antora.
A more comprehensive tutorial will be made available in the documentation.

=== Prerequisites

To preview and bundle the default UI, you need the following software on your computer:

* {uri-git}[git] (command: `git`)
* {uri-node}[Node 8] (command: `node`)
* {uri-gulp}[Gulp CLI] (command: `gulp`)
* {uri-yarn}[Yarn] (command: `yarn`)

==== git

First, make sure you have git installed.

$ git --version

If not, {uri-git-dl}[download and install] the git package for your system.

==== Node 8

Next, make sure that you have Node 8 installed.

$ node --version

If this command fails with an error, you don't have Node installed.
If the command doesn't report a Node 8 version (e.g., v8.9.4), you don't have a suitable version of Node 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 Node 8 using the following command:

$ nvm install 8

You can switch to this version of Node at any time using the following command:

$ nvm use 8

To make Node 8 the default in new terminals, type:

$ nvm alias default 8

Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn.

==== Gulp CLI

Next, you'll need the Gulp command-line interface (CLI).
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'll need Yarn, which is the preferred package manager for the Node ecosystem.

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

Now that you have the prerequisites installed, you can fetch and build the default UI project.

=== Clone and Initialize the UI Project

Clone the default 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.

Use Yarn to install the project's dependencies.
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.

=== Preview the UI

The default UI project is configured to preview offline.
That's what the files in the [.path]_preview-site-src/_ folder are for.
This folder contains HTML file fragments that provide a representative sample of content from the site.

To build the UI and preview it in a local web server, run the `preview` 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 URL 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 Use with Antora

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 UI bundle will be available at [.path]_build/ui-bundle.zip_.
You can then point Antora at this bundle using the `--ui-bundle` command-line option.

== Copyright and License

Copyright (C) 2017-2018 OpenDevise Inc. and the Antora Project.

Use of this software is granted under the terms of the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License Version 2.0] (MPL-2.0).
See link:LICENSE[] to find the full license text.

== Authors

Development of Antora is led and sponsored by {uri-opendevise}[OpenDevise Inc].
@@ -0,0 +1,5 @@
name: antora-ui-default
title: Antora Default UI
version: master
nav:
- modules/ROOT/nav.adoc
@@ -0,0 +1,4 @@
:attachmentsdir: {moduledir}/assets/attachments
:examplesdir: {moduledir}/examples
:imagesdir: {moduledir}/assets/images
:partialsdir: {moduledir}/pages/_partials
@@ -0,0 +1,12 @@
* 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: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]
@@ -0,0 +1,2 @@
:moduledir: ..
include::{moduledir}/_attributes.adoc[]
@@ -0,0 +1,41 @@
= Admonition Styles
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]

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!
@@ -0,0 +1,70 @@
= Build a UI Project for Local Preview
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-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 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]_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 `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 `--ui-bundle` command-line option.
@@ -0,0 +1,37 @@
= 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.

0 comments on commit 21ce558

Please sign in to comment.