Concepts for Working With Hugo

This is a brief description of how I conceive Hugo to work for the things I want to do, which basically is to modify an existing ’template’ for my purposes. In other words, I need to understand the underpinnings of Hugo.

As an “engineer” I’m just looking to slightly modify something that someone else with a lot more knowledge than me has already done. For quite a while I have not been able to grasp how things are actually working. Here I want to record how I’ve come to be able to kae things work.

Discussion

There are several terms that are in constant use when one reads how to modify, or actually create, things: “front matter,” “template,” and that Hugo is much faster than other “static site” generators and that “Blackfriday” is the Markdown interpreter.

The latter two concepts have become ‘knowable’ to me for some time now. I’ve been using Markdown, for about a year, to write up some of my web pages. I look at Markdown as a highly compacted version of a combination of html and css and hence writing a web page that can be viewed in a browser becomes an easy process.

So to understand the various concepts, one must have an understanding of html and css, because it’s all about simplefying having to write html and css.

Fortunately I’ve done html and css as reflected in a couple of my websites, deepcreekanswers.com and deepcreekscience.com, both using html, css and php to handle things that are common to all web pages..

To be able to write things in Markdown and get a good looking web page one has to have some software that takes a text page written in the Markdown syntax and convert that page to html that a browser can understand. Markdown does that by embedding the css into the webpage rather than a separate css file. By the way, this document is written in Markdown.

Unfortunately, although there is a basic specification of what Markdown is, the various translation software products do not have the same translations, either some facets are translated differently, or some specification items are not implemented, or additional syntax has been incorporated. So it’s left to the user to how to go about things. To get an idea about the basic specifications read this.

I have used several software products to write my Markdown files including “LightPaper,” “Macdown,” “RMarkdown,” and “Textastic”

Most of times I use “Textastic” because it has a nice display and I kind of get what the display looks like most of the times so I don’t need the web browser feed back that “LightPaper” and “Macdown” provide.

I use “R Markdown” when I want to format work that I have done with “R” into a document format that turns analysis into high-quality html document.

While most software has their own translations from Markdown to html (or pdf or Powerpoint or Word) format there are a couple of libraries or frameworks that claim to be more universal. These are “Pandoc” and “Blackfriday.”. R Markdown uses Pandoc and Hugo uses Blackfriday.

OK. I know something about html, css, Markdown, and Markdown translations to html and css. But, I’m not a web designer and it took me while to grasp the concept of “templates” that website generators such as hugo and jekyll use. Yes, because I like to go with ‘hot’ trends I did do my website for senstech.com in Jekyll.

The next thing to understand is that Hugo is an application written in the Go (or Golang) language. It’s like Word, or Excell or Powrpoint. This application has built-in a lot of templates. So, the next thing to understand is the notion of templates. The best way to visualize that is from a web designer’s point of view, someone who writes html and css from the ground up. What a web designer might do is to partion a html page and associated css into parts that are fixed and variable. Each of these parts are given a name, the template name. So a web page is hence made up of multiple templates. The variable parts are templates that can be accessed with variables, so that they can be customized for and by indiviual users.

The next item to understand is that each website has one or more themes, a theme being a basic design of the layott of a web page, hence what it looks like when you see it in a browser.

So for Hugo to work, you have to use a theme, and to modify a theme, or to develop one, you have to understand html, css, the templates that are available already inside the Hugo application and how Hugo puts everything together to make a web site. That’s a pretty tall order.

To get a feel of how to make Hugo work there is a pretty good Giraffe Academy series of videos on Hugo. I found it useful to learn the concepts of templates and how Hugo works.

After carefully reading the Hugo documentation about the Hugo’s lookup sequence, going from a page, such as one written in Markdown, to retrieve an appropriate template, and doing a little experimentation, I conclude the following:

1. If the content folder contains a “index.html” file, a blank file with only front matter, then Hugo will look for a template type file as shown in the just referenced page in the table “Examples: Layout Lookup for Home Page” in the “layouts” directory.
2. If on the other hand the file in the “content” folder is named “_index.html” then Hugo will look for a list template with the name “list.html,” in my case, found in the “_default” folder inside the “theme” folder. It’s a bit confusing, but one has to get used to it.