HCC-DOCS

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

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 Hugo, 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. The DocDock theme is provided via a git submodule, so after cloning, run git submodule update --init --recursive in the root of the repo. Run git checkout -b <mybranch> to create a new branch for your changes.

Download and install Hugo

Download the appropriate Hugo tarball from the Hugo releases page.

(Direct links for Linux, Mac, and Windows)

The hugo program is a single binary with no dependencies and does not require root priviledges, so just place it somewhere convenient in your PATH (i.e. ~/bin).

Verify it works by running the command hugo version:

bash-4.4# hugo version
Hugo Static Site Generator v0.51 linux/amd64 BuildDate: 2018-11-07T10:10:13Z

Previewing the site and adding content

Use hugo server to preview the site

The hugo server 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 hugo server command should be run from the root of the repository (i.e. the same directory the config.toml file resides in).

If you're working on your local laptop/deskop:

Run the command:

hugo server -b http://127.0.0.1

You should now be able to preview the website by going to http://localhost:1313 in your web browser.

If you're working in a VM on Anvil:

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

Once that is done, run the command:

hugo server -b http://<instance IP> --bind <instance IP>

where <instance IP> is the 10.71.x.x address of your instance.

You should now be able to preview the website by going to http://<instance IP>:1313 in your web browser.

Note: The hugo server 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.

Adding content

The page content for the site is under the content/ 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 Hugo that are used:

1. Front matter
   Front matter is Hugo-specific metadata added to the page. The format can be TOML, YAML, or JSON. The example here uses TOML, which 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. Shortcodes
   Shortcodes are "helper functions" to add content that would otherwise require using raw HTML. Hugo provides some built-in shortcodes. The DocDock theme also provides its own shortcodes. Shortcodes are added via a {{% shortcodename parameters %}} declaration. For example, to embed a YouTube video with ID -Vh7SyC-3mA:

   {{< youtube -Vh7SyC-3mA >}}

   Other useful shortcodes include language-specific syntax highlighting, figures, and automatic listing of page children for navgiation/summary pages.

3. Using relref for link generation
   The relref shortcode should generally be used for linking to other pages within the site. This will generate relative links that should work no matter what the base URL is. For example, assume you're editing "my_page.md" and want to link to the page "my_other_page.md" in the subdirectory "mystuff". To do so, add the line

   [My other page]({{< relref "mystuff/my_other_page" >}})

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

4. Static content
   Hugo has special handling for static content (images, linked zip files, etc.). In the root of the repo, there is a static/ directory; all static content should go there. Subdirectories can be made to keep things organized; there are existing directories for images and attachments. Feel free to create additional directories if it makes sense. To link to static content, you can use an absolute path from any page. For example, assuming there is an image in the repo at static/images/my_image.png, you can link to it using the figure shortcode as {{< figure src="/images/my_image.png" >}}.

   • 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.

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.