HCC-DOCS

This is the repository for HCC's user documentation. The documentation is a combination of Markdown for the source and the MkDocs static site generator. Currently, the theme used is Material for MkDocs.

The website is viewable at https://hcc.unl.edu/docs.

How to contribute

Since the documentation is a git repo, the standard git workflow of creating a branch for your changes and opening a merge request applies. The steps below detail how to install MkDocs, edit/create content, and preview your changes locally before creating the MR/PR.

Setup your environment

Clone the repo (including submodules) and create a new branch

Clone the repo somewhere convenient.

Download and install MkDocs

MkDocs, the Material for MkDocs theme, and all plugins are installable with pip.

pip install mkdocs mkdocs-material mkdocs-nav-weight \
    mkdocs-material[imaging] mkdocs-awesome-nav mkdocs-macros-plugin \
    mkdocs-table-reader-plugin mkdocs-include-markdown-plugin

Previewing the site and adding content

Use mkdocs serve to preview the site

The mkdocs serve command will build the site and run a small webserver to allow you to preview it. Depending whether you're working on your local machine or a VM on Anvil, the option you pass needs to be slightly different. The mkdocs serve command should be run from the root of the repository (i.e. the same directory the mkdocs.yml file resides in).

This will allow you to view the webiste by going to http://localhost:8080 in your web browser.

Alternatively you can build the HTML files to view in a web browser using the mkdocs build command from the root of the repository.

If you're working in a VM on Anvil:

You'll first need to allow port 8080. If your VM is under the swanson project, there is already an existing "Port 8080" security group. Just add that group to your VM. Otherwise, first create it and allow TCP port 8080 though. You may also need to allow port 8080 through your instance's firewall.

Once that is done, run the command:

mkdocs serve

You should now be able to preview the website by going to http://<instance IP>:8080 in your web browser, where <instance IP> is the 10.71.x.x address of your instance.

Note: The mkdocs serve command will watch the filesystem for changes and force an update in your browswer, so you can simply leave the server running as you work.

Note that the mkdocs serve command will not serve image files. If you need to preview images, you'll need to run nginx via Docker as noted below.

Running nginx using Docker

The built-in mkdocs server doesn't serve images. To fully preview the site either locally or on your VM you'll need to run an nginx container. Install Docker and ensure port 8080 is allowed through to your VM as above if needed.

First build the site by running

mkdocs build

in the repo root. Still in the top-level folder of the repo, then run

docker run -d --name nginx-hcc-docs -v "${PWD}/site:/usr/share/nginx/html:ro" -p 8080:80 nginx:latest

This will start an nginx container in the background. You can then access the site at port 8080 either on localhost or your VM's IP. Note that the autorebuild function does not work here. So you'll need to manually run mkdocs rebuild to pick up changes.

Once you're done, remove the container by running

docker rm -f nginx-docs

Adding content

The page content for the site is under the docs/ directory. The directory structure will determine how the site itself is structured, so place content based on where in the site you would like it to be. Each level in the tree will need to have an index.md file to designate it as a new section. The content itself is almost all standard markdown. However, there are a few things that are specific to MkDocs that are used:

1. YAML Style Metadata
   YAML Style Metadata is mkdocs-specific metadata added to the page. The format needs to be YAML. The example here is for our contact-us page, and is identified by opening and closing --- At minimum, each page should have a title and description:

   ---
   title: "Contact Us"
   description: "Contact Information for HCC"
   ---

   Another useful parameter is the weight option. This will determine the order of display in the navigation tree; lower numbers are displayed before higher numbers.

2. Macros and variables
   Macros are "helper functions" to add content that would otherwise require using raw HTML.

   Currently, a few custom ones are implemented.

   • {{ youtube('Emded_URL_OR_Share_Code') }} - Embeds a youtube video into the docs
   • {{ md_table('path_or_url') }} - Embeds a markdown table as a sortable table.
   • {{ json_table('path_or_url') }} - Embeds a JSON table as a sortable table.

   Variables allow for the use of defining shorthand codes for using the same value in multiple places in the documentation.

   These are all defined in the mkdocs.yml file in the extra: section. Variables are called using {{ variable.path.to.value }} where the path starts after the extra: block.

   extra:
     hcc:  
     # Swan Cluster Specific Information
       swan:
         xfer: "swan-xfer.unl.edu"
         ood:
           name: "Swan Open OnDemand"
           url: "https://swan-ood.unl.edu"
         work:
           block: "100 TiB"

   Using a section of the YAML above we can get the following exampls:

   • {{ hcc.swan.xfer }} would yield the URL for Swan's high speed transfer node
   • {{ hcc.swan.ood.url }} would yield the block quota for Swan's $WORK filesystem
   • {{ hcc.swan.work.block }} would yield the Open OnDemand URL for Swan
   • {{ children('path_after_docs') }} - List child pages and Descriptions - do not add trailing /

   A good file for examples of the use of these variables is docs/handling_data/index.md where many variables are used to discuss the filesystems.

3. Code Blocks

   Code blocks are able to use language specific formatting and use the standard markdown format for codeblocks.

   ``` python
   print('Hello World!')
   ```

4. Links MkDocs uses standard markdown links, [Text to Display](URL or path/to/file)

   Note that you can omit the .md suffix from the filename.

5. Static content

   1. Images Images are stored in docs/images.

      Images can then be embeded in one of two methods. The path starts from the images directory.

      Using markdown: ![Optional Image Title](/image/picture.png)

      Using HTML: <img src="/images/picture.png">

      • HTML will also allow the use of standard img embedding and customization.

   2. Markdown and HTML Files Sometimes there are cases where information is stored statically elsewhere. These files are organized in docs/static

      {% 
          include "relative/path/to/file.html"
      %}

   • Special note for .png files: In order to keep the repo size as small as possible, all images should be png's if possible, and further processed using the pngquant compression tool. This will reduce the size by ~3-4x while keeping good quality. For example, to process and overwrite all png files in a directory, run pngquant --ext .png --force *.png. Do the processing prior to committing the files to the repo, otherwise git will be forced to keep multiple copies as the files are binary.

6. Callouts These are the callouts used to highlight information and have a few customization options.

   Callout Template:

   !!! type "Optional Title"
       Content goes here. It is important to make sure to have space in the markdown file above and below the callout. 
       Content must also be indented 

   A full list of callout types and additional usage information is available in the Material for MkDocs documentation page.

Adding your changes

Once you've got your set of changes, add and commit them to your branch. Push the branch and a CI test job will run to ensure there are no errors generating the site. Open a merge request; upon merge, a deploy job will run to update the production site.