Merge branch 'add-readme' into 'master'

Add readme

See merge request !6

README.md

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

config.toml

@@ -15,10 +15,6 @@ defaultContentLanguage = "en"
 defaultContentLanguageInSubdir= false
 enableMissingTranslationPlaceholders = false
 
-
-[blackfriday] 
-hrefTargetBlank = true
-
 # [Languages]
 # [Languages.en]
 # title = "Documentation for Hugo docDock"