https://github.com/riptano/antora-ui-docs

Last synced: 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/riptano/antora-ui-docs
Owner: riptano
License: mpl-2.0
Created: 2021-05-25T17:40:17.000Z (about 5 years ago)
Default Branch: main
Last Pushed: 2024-03-03T21:15:56.000Z (over 2 years ago)
Last Synced: 2025-12-28T16:21:58.221Z (6 months ago)
Language: CSS
Size: 69.1 MB
Stars: 1
Watchers: 8
Forks: 0
Open Issues: 15
Metadata Files:
- Readme: README.adoc
- License: LICENSE

Awesome Lists containing this project

README

= DataStax Antora UI
// Variables:
:current-release: prod-21
// Settings:
:!example-caption:
:experimental:
:hide-uri-scheme:
:toc: macro
ifndef::env-github[]
:icons: font
:toc-title: Contents
endif::[]
ifdef::env-github[]
:important-caption: :exclamation:
:note-caption: :paperclip:
:!toc-title:
:badges:
endif::[]
// Project URIs:
:project-repo-name: riptano/antora-ui-docs
:url-repo: git@github.com:{project-repo-name}.git
:url-project: https://github.com/{project-repo-name}
:url-site: https://docs.datastax.com
:url-coppi: https://coppi.aws.dsinternal.org
:url-docs-preview: http://docs-preview.datastax.com
// External URIs:
:url-antora: https://antora.org
:url-git: https://git-scm.com
:url-git-dl: {url-git}/downloads
:url-gulp: http://gulpjs.com
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation
:url-datastax: https://datastax.com
:url-docs-home: https://github.com/riptano/docs-home

ifdef::badges[]
image:https://img.shields.io/static/v1?label=release&message={current-release}&color=blue[Latest Release,link={url-project}/releases/download/{current-release}/ui-bundle.zip,format=svg]
endif::[]

toc::[]

This project is used to develop and distribute the UI for the {url-site}[DataStax documentation site].

The UI bundle this project produces is intended to be used with {url-antora}[Antora].
The UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and _site-wide_ images.
As such, it provides both the visual theme and user interactions for the documentation site.

The base code for this project is supplied by the {url-antora-default-ui}[Antora Default UI], with DataStax-specific components templated over the top.

[#usage]
== Usage

To use this UI with Antora, add the following configuration to your playbook file:

[source,yaml,subs=attributes+]
----
ui:
bundle:
url: https://github.com/riptano/antora-ui-docs/releases/latest/download/ui-bundle.zip
snapshot: true
----

NOTE: The `snapshot` flag tells Antora to fetch the UI when the `--fetch` command-line flag is present.
This setting is required because updates to the UI bundle are pushed to the same URL.
If the URL were to be unique, this setting would not be required.

[#search-dependencies]
=== About site search UI dependencies

Additional tasks must be performed in order for the site search functionality on {url-site}[docs.datastax.com] to work properly.
These tasks only need to be performed when changes are made to the following files:

[%header.autowidth.stretch]
|===
|Files |Tasks

|{url-project}/blob/main/gcx/algoliaSearch/index.html[_gcx/algoliaSearch/index.html_]
|Copy this file to the _/en/search_ directory on the {url-coppi}/en/search/[coppi] and {url-docs-preview}/en/search/[docs-preview] servers.

|{url-project}/tree/main/gcx/algoliaSearch/src[_gcx/algoliaSearch/src/*_]
|Copy these files to the _playbooks/supplemental-ui_ directory in the {url-docs-home}/tree/main/playbooks/supplemental-ui[docs-home] repository.
|===

In the {url-docs-home}[docs-home] repository, the {url-docs-home}/blob/main/playbooks/site-local-home.yaml[_site-local-home.yaml_] and {url-docs-home}/blob/main/playbooks/site-publish-home.yaml[_site-publish-home.yaml_] playbooks are configured to incorporate the files from the _supplemental-ui_ directory into the assets directory of the generated site:

[source,yaml]
----
ui:
supplemental_files:
- path: css/siteSearch.css
contents: ./supplemental-ui/siteSearch.css
- path: js/siteSearch.js
contents: ./supplemental-ui/siteSearch.js
output_dir: assets
----

Whenever files are changed or added within the _supplemental-ui_ directory, the `home` docset must then be built and deployed to all of the docs servers to ensure that the servers have the latest site search assets.

[source,console]
----
bsys build home
bsys deploy home coppi
bsys deploy home docs-preview
bsys sync
----

.coppi asset locations
----
/var/www/en/home/assets/css/siteSearch.css
/var/www/en/home/assets/js/siteSearch.js
----

.docs-preview asset locations
----
/datastax/www/docs.datastax.com/en/home/assets/css/siteSearch.css
/datastax/www/docs.datastax.com/en/home/assets/js/siteSearch.js
----

== Development quickstart

This section offers a basic tutorial to teach you how to set up the UI project, preview it locally, and bundle it for use with Antora.
A more comprehensive tutorial can be found in the documentation at {url-antora-docs}.

[#dev-prerequisites]
=== Prerequisites

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

* {url-git}[git] (command: `git`)
* {url-nodejs}[Node.js] (commands: `node` and `npm`)
* {url-gulp}[Gulp CLI] (command: `gulp`)

==== git

First, make sure you have git installed.

[source,shell]
----
git --version
----

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

==== Node.js

Next, make sure that you have Node.js installed (which also provides npm).

[source,shell]
----
node --version
----

If this command fails with an error, you don't have Node.js installed.
If the command doesn't report an LTS version of Node.js (e.g., v16.17.1), it means you don't have a suitable version of Node.js installed.
In this guide, we'll be installing Node.js 16.

While you can install Node.js from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to manage your Node.js installation(s).
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.

Once you've installed nvm, open a new terminal and install Node.js 16 using the following command:

[source,shell]
----
nvm install 16
----

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

[source,shell]
----
nvm use 16
----

To make Node.js 16 the default in new terminals, type:

[source,shell]
----
nvm alias default 16
----

Now that you have Node.js installed, you can proceed with installing the Gulp CLI.

==== Gulp CLI

You'll need the Gulp command-line interface (CLI) to run the build.
The Gulp CLI package provides the `gulp` command which, in turn, executes the version of Gulp declared by the project.

You can install the Gulp CLI globally (which resolves to a location in your user directory if you're using nvm) using the following command:

[source,shell]
----
npm install -g gulp-cli
----

Verify the Gulp CLI is installed and on your PATH by running:

[source,shell]
----
gulp --version
----

If you prefer to install global packages using Yarn, run this command instead:

[source,shell]
----
yarn global add gulp-cli
----

Alternately, you can use the `gulp` command that is installed by the project's dependencies.

[source,shell]
----
$(npm bin)/gulp --version
----

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

=== Clone and initialize the UI project

Clone the UI project using git:

[subs=attributes+]
----
git clone {url-project} &&
cd "`basename $_`"
----

The example above clones the UI project and then switches to the project folder on your filesystem.
Stay in this project folder when executing all subsequent commands.

If you are testing UI bundle changes from a PR that is not yet merged to `main`, checkout the branch. Example:

[source,shell]
----
git checkout feature/new-helios-base
----

Use npm to install the project's dependencies inside the project.
In your terminal, execute the following command:

[source,shell]
----
npm 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 and should _not_ be committed back to this repository.

[TIP]
====
If you prefer to install packages using Yarn, run this command instead:

[source,shell]
----
yarn
----
====

=== Preview the UI

This UI project is configured to preview offline.
The files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action.
In this folder, you'll primarily find pages written in AsciiDoc.
These pages provide a representative sample and kitchen sink of content from the real site.

If you are testing UI bundle changes from a PR that is not yet merged to `main`, and if you haven't already, remember to checkout the branch. Example:

[source,shell]
----
git checkout feature/new-helios-base
----

Run the `npm install` command again.

[source,shell]
----
npm install
----

Now, to build the UI and preview it in a local web server, run the `preview` command:

[source,shell]
----
gulp preview
----

You'll see a URL listed in the output of this command:

....
[12:00:00] Starting server...
[12:00:00] Server started http://localhost:5252
[12:00:00] Running server
....

Navigate to this URL to preview the site locally.

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]
=== Package for use with Antora

If you need to package the UI so you can use it to generate the documentation site locally, run the following command:

[source,shell]
----
gulp bundle
----

If any errors are reported by lint, you'll need to fix them.

When the command completes successfully, the UI bundle will be available at [.path]_build/ui-bundle.zip_.
You can 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:

[source,shell]
----
gulp bundle:pack
----

The UI bundle will again be available at [.path]_build/ui-bundle.zip_.

=== Package for use with Antora adding Helios GCX

To include Helios GCX to the Antora bundle, you can build it following these steps:

Install the Node dependencies from the `./gcx` folder:

[source,shell]
----
cd ./gcx
npm install
----

Once it finished, you can run on this folder:

[source,shell]
----
npm run bundle
----

This script will run both Antora and Helios bundlers, the final build you can find it on `./gcx/build` as `ui-bundle.zip`

==== Source maps

The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
{url-source-maps}[Source maps] correlate these combined files with their original sources.

This "`source mapping`" is accomplished by generating additional map files that make this association.
These map files sit adjacent to the combined files in the build folder.
The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.

In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them.
If you need to include source maps in the bundle, you can do so by setting the `SOURCEMAPS` environment variable to `true` when you run the bundle command:

[source,shell]
----
SOURCEMAPS=true gulp bundle
----

In this case, the bundle will include the source maps, which can be used for debugging your production site.

== Release the UI bundle

Once you're satisfied with the changes you've made to the UI and would like to make those changes available to Antora, you'll need to publish the UI as a bundle by making a release.
The bundle can then be downloaded from this repository using a unique URL.
You can see a list of all past releases on the {url-project}/releases[releases page].

NOTE: All DataStax docs are configured to pull the latest, non-pre-release UI bundle.
See the <> section for an example of how this behavior is configured in a site playbook.

=== Release task workflow

In addition to the <> covered above, you'll need to complete the following steps to release a new UI bundle:

. Pack the UI bundle as described in <>.
+
[source,shell]
----
gulp bundle
----

. Follow the GitHub instructions for {url-create-release}[creating a release].
.. Create a new tag using the next version number in the sequence (e.g., prod-2 after prod-1)
.. Make sure that the new tag targets the `main` branch.
.. Title the release with the same name as the tag.
(The release title and the tag name should always be the same, as it makes releases easier to identify.)
.. (Optional) Add a description for the release that highlights the functional changes that have been added since the last release.
.. Attach the UI bundle, located in [.path]_gcx/build/ui-bundle.zip_`, as a release asset.
.. Check the box labeled *This is a pre-release* if you don't want the release to be generally available.
+
Selecting this option is helpful if you want to publish a new UI bundle for testing purposes (production builds of the DataStax documentation are only configured to consume the latest _non-pre-release_ UI bundle).
You can then edit the release in the future to remove the *Pre-release* label, if desired.
+
CAUTION: If you do not check this box, then the release is immediately promoted to *Latest*, and all DataStax docs will consume the new UI bundle the next time they are built.

. Update the `:current-release:` attribute in the header of this README to reference the tag of the latest bundle (if it is not pre-release), then commit that update to the repository.

== Hero block
There are two files that need to be updated in order to include the hero block in a page

* helios-gcs-heroBlock.css
* The .adoc file you want to add the hero block

=== Define Background css

. To define the hero block background, it needs to be done in the `helios-gcs-heroBlock.css` file located under /gcx/styles/src/css/ path
. It requires to set the class identifier name/value and the path to the background image which can be an svg file.
. The class identifier name/value would be any meaningful value you would like to use to identify the background image.
.. The identifier name will be used to reference the background image in the .adoc where the hero will be setup.
.. If the identifier name is not defined, it will use the default setup image.

For the below code portion .dsHeroBlock, .dsHeroBlock[data-banner="default"] would be the default image to set in case no identifier or "default" identifier is set
-----
.dsHeroBlock,
.dsHeroBlock[data-banner="default"] {
background-image: url('../img/hero-banner-1.svg');
background-size: cover;
color: white;
font-family: 'Roboto', sans-serif;
}
-----

To set a specific background image, it will be done by setting the identifier value and the image path
----
.dsHeroBlock[data-banner="alternative"]{
background-image: url('../img/hero-banner-2.svg');
}
----

=== Define the hero block in a .adoc file
The structure to set a hero block in an `.adoc` file is as shown in the code block below. This will add the hero block to the top of the page which will have a background, title, content.

. Hero Block background (class="dsHeroBlock")
.. This is set by adding `

` where the "data-banner identifier will be the name especified for the image in the `helios-gcs-heroBlock.css` file.
. [.hero.title]
.. This tag is used to set the hero banner title
. [.hero.content]
.. This tag is used to set the hero banner content under the title.

----
++++

++++

[.hero.title]
Documentation Home

[.hero.content]
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

++++

++++
----

== Copyright and license

=== Antora Default UI

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).

=== Branding and design

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/riptano/antora-ui-docs

Awesome Lists containing this project

README