A ‘bare bones’ instructional site using Hugo and PicoCSS styling.
The benefit of Hugo is that it allows a solopreneur to reduce the overhead of managing a content platform. You want to manage your site simply by editing mediawiki content files in Neovim or whatever. But you also need to keep doing styling/layout modifications so you cannot afford for that to become more complicated/cumbersome. Hugo breaks up the work of layout/styling in a way that makes sense for the structure of your content.
As your site/business expands, you want to add features, like site-wide color changes, UI libraries, back-end integration to perhaps Cloudflare Workers. This project will show that in stages, using different commits.
These initial paragraphs live in content/_index.md. Layout is determined by layouts/index.html.
Add variables at the top of the content/_index.md file, to parameterize how the front page is layed out. For example, I’ve added a ‘redborders’ variable to visually debug the homepage when necessary. This variable is used by layouts/index.html.
New Sections
You add a section to this homepage with $ hugo new content <filename> and edit the new content/filename.md file to set order (i.e. ‘weight’), content etc.
When you add content files, the Hugo server live updates in your browser, unlike with updates to layouts/*.html files which require a manual browser refresh.
Workflow-wise you might block out a bunch of sections for a new site for some project, and then hop into the .md files and style them each with unique local html, as shown here.
The navbar will automatically update, because the homepage layout reads the content files and builds out the options based on it. Most Hugo themes need you to manage a separate list of navbar items in hugo.toml which adds to code coupling.
Structure
hugo.toml
layouts/_default/baseof.html # wraps every request with site-wide html
layouts/_default/single.html # lays out content/* != _index.md
layouts/index.html # lays out the homepage
archetypes/default.md # template for all content files
content/_index.md
HUGO.TOML EXAMPLE
baseURL = "https://kickstartplatforms.com/"
title = 'Kickstart'
[taxonomies] # empty so explicitly undefined
- baseURL replaces absolute links
- title is a parameter used in layout files
- taxonomies is helpful for bigger sites, not necessary right now
CONTENT/ vs LAYOUTS/
Each content file matches a web resource path, eg https://website.com/ retrieves content/index.md. So that file must exist, and so must a matching layout file, layouts/index.html.
The matching rules are explained in depth later, but here’s another example: https://website.com/<anything>.html => content/<anything>.md => layous/_default/single.html
_default/baseof.html provides site wide html, and wraps every layouts/ file retreived.
Store
Signup
This is the content/signup.md file.
We could delete the title variable in the content file, and write out the signup form directly here. It will still be wrapped by baseof.html and index.html.