Hugo: Starting Without a Theme
But the Official Docs Use a Theme?
I know. And using a theme is great, I’m not saying that you shouldn’t. However, if you want to learn how to build a quick, complete and straightforward site, using a theme forces you into the theme builders constraints immediately. In my case, I searched through a whole slew of themes and, whenever I found one that I kinda liked, realized that it hadn’t been updated in a really long time.
This was a problem for me until I realized how easy it was to setup a site without a theme. Now, it was easy once I figured it out, getting there wasn’t exactly easy.
Appreciating Simplicity
Before we do that though, we need to address something that I brough up about the downside of working with Hugo (or static site generators in general) compared to something like Wordpress. That downside is that you are thrust into having to deal with technical issues sooner when working with a static site. Now, this actually isn’t always the case, if you want even some basic level of customization on a Wordpress site, you’ll need to get comfortable with configuration options and MySQL databases pretty quick. However, for the raw experience of a nice web front end to create your content, Wordpress is great and Hugo and other static sites don’t come installed with anything like that.
However, this isn’t always a weakness and in some cases it can be a strength. In this case, the simplicity is the strength. We’re going to create the most basic of text files and publish that out on our site.
So, open up a text editor and simply type:
# Hello World!
and save the file with a file name of my-first-post.md . Seriously, that’s it, but even this can be confusing. So, type that entire line include the number sign|pound sign|hashtag at the beggining of the line. Then save the file and make sure the name of the file is my-first-post.md . Notice how the filename ends with .md , that is really important in this case and I’ll talk more about why that is later.
Create a New Hugo Site
Creating a new hugo site is straightforward. However, it does require you to be at a terminal.
$ hugo new site my-new-site
When you type out that command, remember, you don’t need to type out the $ , showing it that way here in this blog is a convenient way to show what it would look like in your terminal, hugo will create a new directory name my-new-site and it’ll setup all the right folder structures for you within that directory.
Hugo Directory Structure
Since our my-first-post.md file is the first piece of content that we have written for our blog, let’s move that content into the content/ directory.
So far, things have been pretty easy. Let’s recap: our first step was to create a file, my-first-post.md and our second step was to create a new hugo site using the hugo new command. Our last step was to move the file we created into the content/ directory. Keep in mind that I show the slash when writing about a directory here on this blog post in order for you to easily distinguish that it is a directory and not a file.
There is only one more step to publishing our first piece of content, and that is to specify our content’s layout. In order to do that, Hugo defines a directory for that purpose, that directory is layouts/_default. Hugo doesn’t come with the _default/ directory from the start, so we’ll need to create it, we can do that by typing in:
$ mkdir layouts/_default
And you should have a directory underneath layouts. We’ll talk a lot more about layout directories and how they work in later articles. The important thing to realize is that directories are relatively easy to create, and, by doing so, you can create a nicely structured way to organize the content on you site.
Phew, were almost done, we just need to create an actual layout. For that, type the following content into a file named basof.html and then place that file in the _default directory.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>my-new-site</title>
</head>
<body>
{{ .Content }}
</body>
</html>
There are, for sure, easier ways for you to get access to a file that contains the base template of an html page. However, what is important is that, even while this isn’t the easiest process, it does give you 100% complete control of what is in the HTML on your site. Lots of other providers will load a whole boat load of tools, analytics, trackers and other things that will either bloat the size of your site or even perhaps limit what you can do on your site.
Once that file is there, you can type in:
hugo -D serve
and you should be able to see your first piece of content by typing
localhost:1313/my-first-post/
in your browser and you should see this screenshot.
Review
Eeesh, that was a lot of typing out around a terminal to complete that, yeah? I would agree, things aren’t always the easiest. And there certainly are some no-code tools and sites that will put together a landing page for you. However, that landing page is going to look crazy, crazy similar to many other landing pages out there, and, once you want to customize that landing page, you will undoubtedly run up against limits of what you can do.
Those limits are in place because the companies providing those tools are trying to remove this complexity to make things easier for you. However, this complexity is also the very thing that give you the ability to differentiate what you are doing. That’s where the real power here lies. Yes, creating a site this way was slightly more difficult because it was done with a terminal and command line, but it offers you way, way more customization options down the road.
What separates this approach for others is that you have managed to keep all of your customization options open to you and for that, the only thing you needed to trade so far was a few commands to type in at the terminal.