This project is used to develop and distribute the UI for the Couchbase documentation site. The UI bundle this project produces is intended to be used with 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 rest of the material for the documentation site comes from the content repositories.
You can view a preview of this UI online at cb-docs-ui.netlify.com.
To use this UI with Antora, add the following configuration to your playbook file:
ui:
bundle:
url: https://github.com/couchbase/docs-ui/releases/download/v183/ui-bundle.zipRead on to learn how to develop the UI.
This section offers a basic tutorial to learn how to set up the UI project, preview it locally, and bundle it for use with Antora.
To preview and bundle the UI, you need the following software on your computer:
First, make sure you have git installed.
$ git --version
If not, download and install the git package for your system.
Next, make sure that you have Node 8 installed.
$ node -v
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.11.4), then 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 nvm (Node Version Manager) to install and manage Node. Follow the 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 Yarn and the Gulp CLI.
Next, 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
Verify Yarn is installed and on your PATH by running:
$ yarn -v
Finally, 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
If you prefer to install global packages using Yarn, run this command instead:
$ yarn global add gulp-cli
Verify the Gulp CLI is installed and on your PATH by running:
$ gulp -v
Now that you have the prerequisites installed, you can fetch and build the UI project.
Clone the UI project using git:
$ git clone https://github.com/couchbase/docs-ui && cd "`basename $_`"
The example above clones the Couchbase docs UI project and then switches to the project folder on your filesystem. Stay in this project folder when executing all subsequent commands.
Use Yarn to install the project’s dependencies inside the project. In your terminal, execute the following command:
$ yarn install
This command installs the dependencies listed in package.json into the node_modules/ folder inside the project. This folder does not get included in the UI bundle and should not be committed to the source control repository.
The UI project is configured to preview offline. The files in the preview-site-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.
To build the UI and preview it in a local web server, run the preview command:
$ gulp preview
You’ll see a URL listed in the output of this command:
[18:24:29] Server started http://localhost:5252 [18:24:29] 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 build task if a change is detected, and sending the updates to the browser.
Press Ctrl+C to stop the preview server and end the continuous build.
You can share a preview of the UI online by submitting a pull request to GitHub. The repository is configured to create a deploy preview on Netlify for every pull request. Here’s how that process works:
-
Fork the repository on GitHub (only has to be done once).
-
Create a local branch.
-
Make changes to the UI.
-
Commit your changes to that branch.
-
Push that branch to your fork (on GitHub).
-
Submit a pull request from the branch you pushed to your fork.
-
Wait for deploy/netlify check to say “Deploy preview ready” on the pull request page.
-
Click on the “Details” link under “Show all checks” on the pull request page.
-
View your changes in the deploy preview or share the URL with others.
The deploy preview works because there is a webhook on the repository that pings https://api.netlify.com/hooks/github for the following events: push, pull_request, delete_branch. Netlify then runs the command specified in netlify.toml, deploys the site, and allocates a temporary URL for it.
If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
$ gulp pack
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 build/ui-bundle.zip.
You can point Antora at this bundle using the --ui-bundle-url command-line option (e.g., --ui-bundle-url=../docs-ui/build/ui-bundle.zip).
To control the visual appearance of pages, the UI bundle provides a CSS stylesheet (for changing the CSS style rules) and any number of layouts in the form of Handlebars templates (for changing the HTML). Although most styles are used on all pages, it’s possible to configure styles to target certain pages either based on the layout or page role. This section will introduce these various options and explain how they work.
The most drastic way to change the appearance of the page is to change the HTML. The HTML is controlled by layouts, which are Handlebars templates located in src/layouts. A layout typically includes partials, located in src/partials, which are reusable template fragments. Partials may, in turn, include other partials.
This project currently has three layouts:
-
default.hbs
-
404.hbs
-
home.hbs
If a page doesn’t specify a layout, the default.hbs layout is used.
To specify a layout, the page file must declare the page-layout document attribute in the AsciiDoc header.
The value of that attribute should match the stem of the layout file (the filename minus the file extension, e.g., home).
For example, the home page declares the following document attribute in the AsciiDoc header:
= Welcome to the Couchbase Docs!
:page-layout: homeIn this case, Antora will select the home.hbs layout for this page instead of default.hbs. Using a dedicated layout affords a lot of control over what gets displayed on this page. Every layout has access to the same UI model.
The home page likely requires additional styles that are only relevant for that page.
You can organize these styles inside a namespace by adding a dedicated class to the <body> tag.
In fact, that’s what the home.hbs layout currently does.
<body class="home">
...
</body>You can now define styles that are scoped to that page as follows:
.home h1,
.home h2,
.home h3 {
line-height: 1.2;
margin: 0;
}To make these styles easier to find and manage, they should be organized in a dedicated file src/css/home.css and included into the master src/css/site.css file, which is how this project is currently configured.
When you run the preview, you can see the home page by visiting the URL http://localhost:5252/home.html.
The 404.hbs layout is similar to other layouts, except Antora selects it automatically to make the 404 page (404.html).
For this page, the page variable in the UI model is reduced to page.layout and page.title.
None of the other data in the page variable is applicable for this page.
When you run the preview, you can see the 404 page by visiting the URL http://localhost:5252/404.html.
Creating a new layout is powerful, but incurs a lot of maintenance overhead. If you’re only looking to tweak the visual appearance of the article region of the page, perhaps to support custom UI components, you can instead define a page role.
A page role is a special role that can be assigned per page that’s typically applied directly to the main article. It’s a way to activate CSS that is scoped to a given page or group of pages.
To apply a page role, the AsciiDoc file for the page must declare the page-role attribute in the AsciiDoc document header.
For example, the Starter Kits page declares the tiles role as follows:
= Starter Kits
:page-role: tilesThe value of this attribute is added by the src/css/body.hbs template to the class attribute of the .body element.
<div class="body container{{#if page.attributes.role}} {{page.attributes.role}}{{/if}}">
...
</div>Therefore, setting the page-role attribute to tiles activates any CSS under the .body.tiles selector.
For example:
.body.tiles .doc {
display: flex;
flex-wrap: wrap;
margin-right: -1.25rem;
}These and other styles organize the sections of the page into tiles. When you run the preview, you can see the tiles role in action by visiting the URL http://localhost:5252/tiles.html.
You can create as many of these roles as you like simply by adding CSS scoped to the name of a role.
The playbook for the Couchbase documentation includes a tabs block extension. The extension takes care of converting the AsciiDoc for the tabs to HTML. The UI provides the interaction (JavaScript) and styles (CSS) that power these tabs.
You can find the JavaScript for the tabs in the file src/js/05-tabset.js. You can find the styles for the tabs in the file src/css/doc.css. The preview site provides an example of these tabs in the file preview-site-src/index.adoc. Note that authors should never enter the HTML for tabs directly, but it is entered this way in the preview site to make it easier to work with.
You can create an arbitrary number of pages for the preview site.
To make a page, create a new AsciiDoc file inside the preview-site-src folder.
You can then access the page in the preview site using the URL pattern http://localhost:5252/<stem>.html, where <stem> is the stem of the source file (the filename minus the file extension).
These preview pages serve the purpose of testing the page layout and content styling. Each page may declare a layout, role, or both.
The only caveat is that, at the moment, every page provides the same UI model (with a few exceptions). The model is defined in preview-site-src/ui-model.yml file. The exceptions include the layout, role, title, contents, and, in the case of home.adoc, the component, which get updated dynamically by the build.
For information about what goes in the UI model, refer the Handlebars templates page in the Antora documentation.
This UI provides integration with Algolia search. The Algolia client is configured in the file src/partials/footer-scripts.hbs. You can test the search directly from the preview site by setting the following environment variables in your shell:
-
ALGOLIA_APP_ID- the application ID that hosts the search index (optional if you’re using docsearch) -
ALGOLIA_API_KEY- your API key for Algolia -
ALGOLIA_INDEX_NAME- the name of the index
You can point to any index that is publicly accessible.
This UI provides integration with JIRA feedback.
The JIRA feedback widget is configured in the file src/partials/footer-scripts.hbs.
You can test the feedback widget directly from the preview site by setting the FEEDBACK_BUTTON=true environment variable in your shell.
The configuration for the widget is currently hardcoded into the partial template.
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. This project provides a Gulp build task, appropriately named release, that fully automates the release.
The release task tags the repository and publishes the bundle to the releases section of the repository on GitHub. The bundle can then be downloaded using a unique URL, accessible from the release page. You can see a list of all past releases on the releases page.
Releasing the UI bundle consists of the following tasks:
-
Pack the UI bundle.
-
Tag the git repository using the next version number in the sequence (e.g., v100 after v99)
-
Create a GitHub release from that git tag.
-
Attach the UI bundle to that release as an asset in zip format.
-
Update the README to reference the URL of the lastest bundle and commit that update to the repository.
Fortunately, you don’t have to do any of these steps yourself.
These steps are fully automated by the gulp release task.
In fact, you don’t even have to run the gulp release task manually.
When a commit is pushed to the master branch of the repository, it triggers the CI job named release-docs-ui-bundle, which executes the gulp release task using pre-configured credentials.
|
❗
|
A release will only be made if the project validates.
To validate the project, run gulp pack before pushing your changes to GitHub.
|
The release-docs-ui-bundle CI job is already configured, so there’s nothing you need to do to make automated release work.
All you have to do is commit your changes and push those commits to the master branch of the git repository.
A few seconds later, a new bundle will be available for use with Antora.
Run git pull to retrieve the updated README that includes the new URL.
|
Tip
|
If you want to commit a change to master without making a release, add the string [skip release] to the end of the commit message.
|
The next two sections document how the CI job is set up an configured.
In addition to the Prerequisites covered above, you’ll need a personal access token for the automated GitHub account, cb-docs-robot, so it has permission to make changes to the repository on GitHub. The cb-docs-robot account will need at least write access to the github.com/couchbase/docs-ui repository, though admin access is recommended.
Start by creating a personal access token for the cb-docs-robot user.
The release task relies on this token to interact with the GitHub API to create the tag, create the release, and upload the asset.
The token must have the public_repo scope.
No other scopes are required (as long as the cb-docs-robot account has write access to the repository).
Next, copy the token generated and store it as a Secret text Jenkins credential as follows:
-
Kind: Secret text
-
Scope: System (Jenkins and nodes only)
-
Secret: <enter-token-value>
-
ID: docs-robot-api-key
-
Description: GitHub API key for docs robot
The token gets passed to the task as the GITHUB_TOKEN environment variable.
In the CI job configuration, covered in the next section, you’ll learn how this token gets transferred from the Jenkins credential to the GITHUB_TOKEN environment variable when the build executes.
Jenkins is used to execute the CI job that publishes the UI bundle. The job is named release-docs-ui-bundle and can be found under the Antora folder in the Jenkins server managed by the Couchbase docs team. This section describes in detail how that job has been configured in case it must be recreated.
The release is performed by the cb-docs-robot GitHub account, which interacts with GitHub entirely using the GitHub API.
The release script authenticates with the GitHub API as the cb-docs-robot user using a personal access token retrieved from the GITHUB_TOKEN environment variable.
Create a new CI job from the Freestyle project template. On the configuration screen, select or populate the following settings:
- General
-
-
Project name:
release-docs-ui-bundle -
Description: Packs, tags, and releases the UI bundle whenever a non-ignored commit is pushed to the master branch of this repository.
-
✓ GitHub project
-
Project url:
https://github.com/couchbase/docs-ui
-
-
- Source Code Management
-
-
✓ Git
-
Repository URL:
https://github.com/couchbase/docs-ui -
Branches to build > Branch Specifier:
*/master -
Additional Behaviours
-
Polling ignores commits with certain messages
-
Excluded Messages:
(?s)(?:Release v\d|.*\[skip .?\]).*
-
-
Advanced clone behaviours
-
Shallow clone: [x]
-
Shallow clone depth:
1 -
Do not fetch tags: [x]
-
Honor refspec on initial clone: [x]
-
-
-
-
- Build Triggers
-
-
✓ GitHub hook trigger for GITScm polling
-
- Build Environment
-
-
✓ Provide Node & npm bin/ folder to PATH
-
NodeJS Installation: node8
-
-
✓ Use secret text(s) or file(s)
-
- Bindings
-
-
Secret text
-
Variable:
GITHUB_TOKEN -
Credentials > (•) Specific credentials: GitHub API key for docs robot
-
-
- Build
-
-
Execute shell
-
Command:
rm -rf build public yarn && ./node_modules/.bin/gulp release
-
-
The Secret text binds the value of the personal access token for the cb-docs-robot read from the specified Jenkins credential to the GITHUB_TOKEN environment varaible.
This environment variable is used by the release task to authenticate against the GitHub API as the cb-docs-robot user.
The heart of the build is the Execute shell section.
Since Jenkins retains the workspace between runs, it’s necessary to start by removing artifact left behind by previous builds.
Next, the dependencies are installed or updated by the call to yarn.
Thanks to the workspace cache, Yarn finds most of the dependencies in the workspace and thus the call to it is very fast.
Finally, the job delegates to Gulp to perform the release steps described in Release Task Workflow.
Once the CI job runs and a new UI bundle is available, you can update the URL of the UI bundle in the Antora playbook file. See Usage for details.
The build trigger requires coordination with the github.com/couchbase/docs-ui repository on GitHub. Specifically, the GitHub repository must be configured to ping the Jenkins webhook whenever a commit comes in.
Jenkins will attempt to set up this link for you when you create the job using the GitHub API key specified under Jenkins › Manage Jenkins › Configure System › GitHub › GitHub Servers. In order for this to work, the cb-docs-robot account must temporarily have admin access to the github.com/couchbase/docs-ui repository. If Jenkins fails to establish that link, you’ll need to set it up manually, which is covered below.
If you have admin access to the repository on GitHub, you can see the details of this webhook by navigating to github.com/couchbase/docs-ui/settings/hooks. Here are the details of that webhook:
- Payload URL
-
JENKINS_URL/github-webhook/ <1>
- Content type
-
application/json
- Secret
-
hidden
- Which events would you like to trigger this webhook?
-
-
✓ Just the
pushevent
-
<1> JENKINS_URL is a placeholder for the real URL of the Jenkins server.
You can also find a list of recent deliveries on that screen.
If Jenkins doesn’t have proper permissions to create the webhook on GitHub, you’ll need to configure it manually. To set up this ping (i.e., webhook), navigate to the Settings › Webhooks page of the GitHub repository. Click Add webhook, enter the following URL in the Payload URL field, then click Add webhook.
JENKINS_URL/git/notifyCommit?url=https://github.com/couchbase/docs-ui&branches=master
(Replace JENKINS_URL with the URL of the Jenkins server).
No secret is required (as this URL does not require authentication).
Update the job configuration to use Poll SCM with an empty schedule instead of GitHub hook trigger for GITScm polling. That will allow this ping to work and prevent Jenkins from showing any warnings.
The software in this repository (build scripts, JavaScript files, Handlebars templates, foundation CSS, utility icons, etc) is part of the Antora project. As such, use of the software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).
Copyright © Couchbase 2018. All rights reserved.