What is the simplest way that profs can use Hugo for their websites?

The Problem

Profs don’t have time or the inclination to learn a lot of web development to create an accessible and secure site. However, they do want a personal site that has a look and feel that is unique.

Observation

The Hugo static site generator is quick to learn, a good reputation and fast. It, also, has many unique and eye catching themes.

Testing

I tried testing two themes. Ananke installed and setup easily and worked. Clarity was very involved and did not work as well. It had decent documentation but was more of a reference. I did not get my content to display correctly using the Hugo standard content placement convention within their setup.

Perhaps, I could use a simpler css framework to style the site?

Using a couple of tutorials that discussed how to take an existing html site and move it to Hugo, I learned that Hugo’s base/default convention is:

  • hugo project folder:

    • archetypes - site wide metadata goes here

    • config.toml - it is as it sounds; your site’s hugo configuration file

      • modified to add asciidoc support, theme used, web server url, etc.

    • content - your content markup files go here, i.e. asciidoc or markdown

      • their folder placement and use of index.adoc or _index.adoc changed how the folder was interpreted by the compiler

    • layouts - holds your html templates

      • _default - the standard template location

        • baseof.html - the page layout template

        • single.html - the single page content partial template

        • list.html - the list page content partial template

      • partials:

        • an optional folder that holds template partials, i.e. header.html, footer.html, etc.

      • shortcodes:

        • an optional folder that holds content template partials

    • static - holds images, css, js, etc.

      • css - holds css files

      • images - holds image files.

I then tried using a classless css lib/framework which styles tags based on semantic html. The visual look is not as flashy but sections could be identified easily.

In order of visual appeal and ease of use:

  1. classless css

  2. bahunya css

  3. tufte css

  4. sakura css' vader

  5. pico css

Honorable mentions are:

  1. writ css

  2. missing css

  3. Bamboo css' dark mode

Solution

I think using a classless css framework is a good compromise for someone wanting to use Hugo to produce an accessible and secure site with an appealing theme.

I think the best way to look at Hugo is as a html compiler/transpiller web framework. To truly customize it, you do need to understand web development.

Therefore, if the person has a web developer to assist them, Hugo becomes an even more powerful tool.

Addendum

Advanced features that I liked:

  • you can have a folder be the page bundle, by using _index.adoc

  • an index.adoc at the root of a folder indicates the folder has 'normal' webpages.

Caveats/Gotchas

  • think of partials as functions that you must explicitly pass your variables to.

References

  1. A Complete Guide to Using Hugo

  2. blogs - Hugo with Asciidoctor - Stack Overflow

  3. Trick to get Hugo to work in the UW environment

  4. Migrating existing page to hugo static site generator · Newbeelearn

  5. Convert Your Plain Old HTML Site to Hugo | Zachary Betz

  6. Using Hugo Without a Theme

  7. External learning resources | Hugo

  8. Context And Variables In The Hugo Static Site Generator — Smashing Magazine