UI Design Contribution
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.
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.
To clone the repository using SSH, follow the below steps.
In the GitLab repository, select Clone and then copy the Clone with SSH URL.
Then, type the following command in your local machine.
git clone <clone with SSH URL>
To add new changes and styles to UI, only the docs-ui repository is required.
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.
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.
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
Fetch all branches of upstream.
docs-ui$ git fetch upstream
Switch to the master branch
docs-ui$ git checkout master
Rewrite your master branch with upstream master branch using rebase command.
docs-ui$ git rebase upstream/master
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
To preview UI, run the gulp preview command. You can preview it on → http://localhost:5252 in the browser of your local machine.
[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
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
+ 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.