hugo-plain-theme

Minimum viable Hugo. No CSS, no JS. HTML only. Instructions on how to generate in the README.

4 out of 5 web devs have experienced the following:

1. "Wow, Hugo sounds amazing! Let me try it out!"
2. "Okay, I made a new theme and a brand new page of Markdown in content/!!"
3. "Running hugo server -D now!!! ... Where is it!!!!"

For whatever reason, Hugo, despite being an excellent static site generator for literally any other use case, makes it unreasonably difficult to get a single page of unformatted, uncomplicated, HTML serving to your localhost.

We're going to fix that. From scratch.

Quickstart: Build your own hugo-plain-theme from scratch

# Start a new site, with Hugo.
hugo new site .

# Make a new theme. Tell Hugo we want to use this new theme.
hugo new theme hugo-plain-theme
echo "theme = 'hugo-plain-theme'" >> config.toml

# GOTCHA 1: Hugo doesn't start with any HTML content at all. So we will make some.
hugo new _index.md
echo "Lorem ipsum dolor sit amet" >> content/_index.md

# VERY IMPORTANT: TELL hugo to SERVE CONTENT for your "index.html" template.
# Why the index.html template is left BLANK BY DEFAULT so you see NOTHING BY DEFAULT
# even if you somehow happen upon learning the post has to be named "_index.md" 
# is beyond me.
echo "{{ .Content }}" >> themes/hugo-plain-theme/layouts/index.html

# Serve the site, with drafts on. You should see it now.
hugo server -D

See it in action: A live example website generated from following those instructions exactly and nothing else

Want to brush up on your theory?

• Bryce Wray's "Really getting started with Hugo" goes into even more detail on what Hugo used to be like, and how to keep things simple with it today, without even touching themes.
• zwbetz's "Make a Hugo Blog from Scratch" takes you all the way from hugo new site to a fully-fleshed out vertical slice of a blog.

Or... use this very repo as a submodule instead

# You can't use submodules unless you're already using git. So let's start with that.
git init

# Start a new site, with Hugo.
# --force is necessary because `git init` put stuff in here,
# but hugo normally expects an empty folder.
hugo new site . --force

# Pull this repo in as a submodule.
cd themes/
git submodule add https://github.com/hiAndrewQuinn/hugo-plain-theme.git
cd ..

# Tell Hugo we want to use the plain theme.
echo "theme = 'hugo-plain-theme'" >> config.toml

# GOTCHA 1: Hugo doesn't start with any HTML content at all. So we will make some.
hugo new _index.md
echo "Lorem ipsum dolor sit amet" >> content/_index.md

# Serve the site, with drafts on. You should see it now.
hugo server -D

There is one big benefit to using this as a submodule - and that's that it actually comes with HTML comments in the rendered pages to let you know exactly which layouts were pulled in, where.

So, for example, when I use this theme to build out build-100-websites.fun, I can open the source code of any page generated with this theme and see comments for where the layouts begin and end:

For someone who is totally new to Hugo, I think these simple guidepost comments will prove invaluable.

Deploying to Netlify: Things to check

• Did you add the theme as a proper submodule? Netlify will complain if you give it nested Git repos which aren't in a submodule relationship to one another.
• Did you set drafts to False for content/_index.md? If you didn't, you'll likely still get a blank white screen, with the only HTML in there being a pair of empty <pre></pre> tags.
• Did you use hugo --gc --minify for your build command? Both flags will save you some space, but --gc, I think, strips out the HTML comments the submodule provides.

Github