UI Design Contribution

This page explains how to contribute to the UI/UX of the HPC documentation site. Ensure to review all the prerequisites listed in Getting Started Page before you start. Also, docs-ui is a fork of the Antora’s default UI → Antora default UI

Software Requirements

  • Documentation writers need to install the following software packages for your OS running in your local machine.

    Git, Node Js ,Gulp.

    To install these packages in your local machine, refer to the installation guide for Antora default UI →Installation Guide for UI.

Clone the Repository

Make sure that the SSH key is set up between your local machine and the remote GitLab Server. Refer to the page → Setting Up GitLab on how to connect and setup SSH keys.

  • URLs for docs-ui and docs-site GitLab repositories.

    Folder

    GitLab URL

    docs-ui

    https://gitlab.nmsu.edu/hpc/hpc-antora-ui

    docs-site

    https://gitlab.nmsu.edu/hpc/docs-site

  • To clone the repository using SSH, follow the below steps.

    1. In the GitLab repository, select Clone and then copy the Clone with SSH URL.

    2. Then, type the following command in your local machine.

      Syntax :

    git clone <clone with SSH URL>

To add new changes and styles to UI, only the docs-ui repository is required.

Install the Project Dependencies

Switch to the cloned docs-ui folder in your local machine and run the make build command to install the dependencies for the project

cd docs-ui
docs-ui$ make build

Also, there are other useful make commands for the project. From the project root, run make to see the list of available options.

Keeping GitLab Fork Updated

Because the docs-ui is a fork of the Antora’s default UI, you need to keep the GitLab fork updated and follow the below steps.

Step 1

Add the original repository that’s forked which is Antora’s default UI and call it upstream.

docs-ui$ git remote add upstream https://gitlab.com/antora/antora-ui-default.git

Step 2

Fetch all branches of upstream.

docs-ui$ git fetch upstream

Step 3

Switch to the master branch

docs-ui$ git checkout master

Step 4

Rewrite your master branch with upstream master branch using rebase command.

docs-ui$ git rebase upstream/master

Using Git & Creating branch

Once all the dependencies are installed, create your own branch and work on the UI design. To learn more about branches, committing files and Git commands, refer to → Git commands for HPC documentation

Preview UI

To preview UI, run the gulp preview command. You can preview it on → http://localhost:5252 in the browser of your local machine.

make preview

Output:

[17:20:21] Using gulpfile ~/Desktop/hpc/docs/docs-ui/gulpfile.js
[17:20:21] Starting 'preview'...
[17:20:21] Starting 'build'...
[17:20:25] Finished 'preview:build-pages' after 4.23 s
[17:20:26] Finished 'build' after 4.95 s
[17:20:21] Starting 'preview:build-pages'...
[17:20:26] Starting 'preview:serve'...
[17:20:26] Starting server...
[17:20:26] Server started http://localhost:5252 and http://172.20.20.20:5252
[17:20:26] Running server

Bundle UI

If you want to use UI/UX changes to be reflected on HPC docs site, you need to create a bundle of the UI using the following command.

docs-ui$ make build

Output:

+ gulp bundle
[17:25:58] Using gulpfile ~/Desktop/hpc/docs/docs-ui/gulpfile.js
[17:25:58] Starting 'bundle'...
[17:25:58] Starting 'clean'...
[17:25:58] Finished 'clean' after 58 ms
..
[17:26:06] Finished 'bundle:pack' after 84 ms
[17:26:06] Finished 'bundle' after 8.66 s

New UI bundle will be inside the build directory as ui-bundle.zip under the docs-ui repository.

docs-ui
|_ ui
  |_ ui-bundle.zip

After the ui-bundle is built, refer to → Publish UI changes to docs site on how to use the latest UI bundle for docs-site.