Skip to content
Snippets Groups Projects

Add readme

Merged Add readme
add-readme into master
Merged Adam Caprez requested to merge add-readme into master
Compare
and
2 files
+ 129
− 4
Compare changes
  • Side-by-side
  • Inline
Files
2
README.md 0 → 100644
+ 129
− 0
 
HCC-DOCS
 
========
 
 
This is the repository for HCC's user documentation. The documentation is a
 
combination of [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
 
for the source and the [Hugo](https://gohugo.io) static site generator. Currently,
 
the theme used is [docDock](https://themes.gohugo.io/docdock/).
 
 
The "production" state of the website is viewable at [http://10.71.110.145](http://10.71.110.145)
 
once connected to the Anvil VPN. This will later be moved to the `hcc-docs.unl.edu` server once
 
things are in a reasonable state.
 
 
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 and create a new branch
 
 
Clone the repo somewhere convenient. Run `git checkout -b <mybranch>` to create a new
 
branch for your changes.
 
 
#### Download and install Hugo
 
**Note: The DocDock template currently has errors with the recently released Hugo v0.50. Use v0.49.2 instead until there is a fix.**
 
 
Download the appropriate Hugo tarball from the Hugo [releases page](https://github.com/gohugoio/hugo/releases).
 
 
(Direct links for [Linux](https://github.com/gohugoio/hugo/releases/download/v0.49.2/hugo_0.49.2_Linux-64bit.tar.gz), [Mac](https://github.com/gohugoio/hugo/releases/download/v0.49.2/hugo_0.49.2_macOS-64bit.tar.gz), and [Windows](https://github.com/gohugoio/hugo/releases/download/v0.49.2/hugo_0.49.2_Windows-64bit.zip))
 
 
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.49.2/extended linux/amd64 BuildDate: 2018-10-11T09:57:02Z
 
```
 
 
### 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](https://gohugo.io/content-management/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](https://gohugo.io/content-management/shortcodes) are "helper functions" to add content
 
that would otherwise require using raw HTML. Hugo provides some [built-in](https://gohugo.io/content-management/shortcodes/#use-hugo-s-built-in-shortcodes)
 
shortcodes. The DocDock theme also provides its own [shortcodes](http://docdock.netlify.com/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.
 
 
#### 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.