README.md 6.96 KB
Newer Older
Adam Caprez's avatar
Adam Caprez committed
1
2
3
4
5
6
7
8
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/).

Adam Caprez's avatar
Adam Caprez committed
9
The website is viewable at https://hcc.unl.edu/docs.
Adam Caprez's avatar
Adam Caprez committed
10
11
12
13
14
15
16
17
18
19

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

Adam Caprez's avatar
Adam Caprez committed
20
#### Clone the repo (including submodules) and create a new branch
Adam Caprez's avatar
Adam Caprez committed
21

Adam Caprez's avatar
Adam Caprez committed
22
23
24
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.
Adam Caprez's avatar
Adam Caprez committed
25
26
27
28
29

#### Download and install Hugo

Download the appropriate Hugo tarball from the Hugo [releases page](https://github.com/gohugoio/hugo/releases).

30
(Direct links for [Linux](https://github.com/gohugoio/hugo/releases/download/v0.51/hugo_0.51_Linux-64bit.tar.gz), [Mac](https://github.com/gohugoio/hugo/releases/download/v0.51/hugo_0.51_macOS-64bit.tar.gz), and [Windows](https://github.com/gohugoio/hugo/releases/download/v0.51/hugo_0.51_Windows-64bit.zip))
Adam Caprez's avatar
Adam Caprez committed
31
32
33
34
35
36
37

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
38
Hugo Static Site Generator v0.51 linux/amd64 BuildDate: 2018-11-07T10:10:13Z
Adam Caprez's avatar
Adam Caprez committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
```

### 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>
```
Adam Caprez's avatar
Adam Caprez committed
72
where *\<instance IP\>* is the 10.71.x.x address of your instance.
Adam Caprez's avatar
Adam Caprez committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

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.

Adam Caprez's avatar
Adam Caprez committed
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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](https://pngquant.org) 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.*

Adam Caprez's avatar
Adam Caprez committed
137
138
139
140
141
#### 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.