Hugo and Academic

overview

Hugo makes for generating a static site with GoLang. This site is managed by Hugo and a theme called Academic. While making these entries is pretty straight forward, the task for remembering the right command always escapes me each time. So making an entry to document the options seemed most fitting for my note taking.

why academic

After having use this theme for a couple of months, I have found myself focusing less on the them and more on the entries of data. I really like how I can group posts with projects and write docs which I treat as my notes or progress on learning topics.

Another nice feature is when I want to start learning more about maths I can use this to show formulas by just using Markdown! Fantastic. Some day I hope to also gain more usage of writing content with OrgMode, but I dont see that happening soon.

content types

  1. post
  2. project
  3. talk
  4. publication
  5. docs
  6. widget_page

when to use them

There are some fields that are shared between all content types and to save some typing and reading, here are the commons:

field namedescription
datewhen the project was created
lastmodwhen the project or page was last updated
drafttrue/false controls if the content will be published

post

This type is best for making a blog post. Yes that sentance does sound redundant, but usually this type is associated with a date and is pulled in to a filter when looking across the entire site for posts.

hugo new --kind post post/name-of-post

What the fields mean:

field namedescription
titlethe title of the post
subtitlethe subtile of the post
summarythe summary of the post displayed in list of posts
authorsa list of authers who wrote the post (eg [“author1”, “author2”] )
tagsa list of tags to register with (eg [“tag1”, “tag2”] )
categoriesif tags were not enought… use categories, but same format as tags
featuredtrue/false controls if the post is listed in the featured module
imageinformation for the image of the post
image:placementplacement options: 1 = Full column width, 2 = Out-set, 3 = Screen-width
image:captiontext to be placed to bottom right of image
image:focal_pointfocal point options: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
image:preview_onlytrue/false to just use the image for thumbnails.
projectslist of projects to be associated with (eg [“project1”, “project2”] )

project

Summarizing a project is great for gathering multiple posts under one goal. By summarizing the project you can associate posts to be listed under the “related” section of the project and post.

hugo new --kind docs project/name-of-project

What the fields mean:

The header matter of the project has a couple of nice features:

field namedescription
titlethis is the name of the project
linktitle
summarythe summary of the project
toctrue/false controls if the table of contents will show up
typedocs (this should not be modified, per theme instructions)
menucontrols the sidebar content
menu:topLevel:namenames pages sub-topics to be listed in the sidebar
menu:topLevel:parentset this to define the current pages parent
menu:topLevel:weightcontrols the sidebar position of the item

project menus

This was a little confusing at first, but with some little testing, it made sense and here is my explanation:

The menu creates the top level post of the document or project. On that document will be some header information. The menus on the left and right side are controlled by the header section called menu.

The toplevel represents the current level of the document you are editing. **If this is the _index.md file, then use a short name for the first level of the navigation. As you continue making more files, you have the option of nesting these toplevel values of the document by defining its parent.

the rest…

I have yet to use the other types of content. Perhaps as I grow, I will come back to this section and provide an update.

Markdown

Sections

To make a section, you can use # symbols for marking its h# depth by using the following examples:

h levelnumber of hashespreview
h1#

Heading level 1

h2##

Heading level 2

h3###

Heading level 3

h4####

Heading level 4

h5#####
Heading level 5
h6######
Heading level 6

Tables

| h level | number of hashes | preview                  |
| ------- | ---------------- | ------------------------ |
| h1      | `#`              | <h1>Heading level 1</h1> |
| h2      | `##`             | <h2>Heading level 2</h2> |
| h3      | `###`            | <h3>Heading level 3</h3> |
| h4      | `####`           | <h4>Heading level 4</h4> |
| h5      | `#####`          | <h5>Heading level 5</h5> |
| h6      | `######`         | <h6>Heading level 6</h6> |
[simple link](https://aaronaddleman.com/site/url/path)
[goto sections](#sections)
[link ref below][1]
[1]: https://aaronaddleman.com/this/can/be/at/the/bottom/of/the/document.md

simple link

goto sections

link ref below

Images

Description of image

[![Description of image](https://images.unsplash.com/photo-1516616370751-86d6bd8b0651?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=1950&q=80 "Shiprock, New Mexico by Beau Rogers")](https://images.unsplash.com/photo-1516616370751-86d6bd8b0651?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=1950&q=80)

Code

Putting text inside of ``` and ``` will mark the text as code.

Commenting

I found this really cool project allows commenting with github issues for commenting. Some day I will install it, but for now I am good.