Adding New Docs

This section explains how to create and publish new documentation to the official website→ HPC. Ensure to review all the prerequisites listed in → Getting Started page before you start.

Software Requirements

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

Name

Download URL

Git

Install Git

Node Js

Install Node Js

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 docs to the website, only the docs-site repository is required.

Install the project dependencies

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

cd docs-site
docs-site$ 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.

Using Git & Creating Branch

Once all the dependencies are installed, create your own branch and start writing the docs in AsciiDoc Format. To learn more about branches, committing files and Git commands, refer to → Git commands for HPC documentation

Preview site

To preview the site with the changes which you have made, run the make preview command. This launches a live preview of the website in your local machine.

docs-site$ make preview

Output:

+ gulp
[17:01:02] Using gulpfile ~/Desktop/hpc/docs/docs-site/gulpfile.js
[17:01:02] Starting 'default'...
[17:01:02] Starting 'build'...
[17:01:07] Finished 'build' after 5.08 s
[17:01:07] Starting 'preview'...
[Browsersync] Access URLs:
 -------------------------------------
       Local: http://localhost:3000
    External: http://172.20.20.20:3000
 -------------------------------------
          UI: http://localhost:3001
 UI External: http://localhost:3001

Go to → http://localhost:3000 to preview the site in your local PC

Publish new UI changes to docs-site

New UI changes can be incorporated into the docs-site. Refer to the section → How to bundle UI with gulp? to make new UI bundle. Then, copy and paste the generated ui-bundle.zip file from docs-ui/build folder → docs-site/ui folder.

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