Hugo - Static Files
In our previous checkpoint, we manage to power-on our Hugo project. Now, the next thing to do is to enable the static files for hosting the web assets such as css, js, images etc. This checkpoint explores how we enable them inside our project.
Before we start, please ensure your Hugo development server is still running. This and the following checkpoints won't be asking you to start your server (etc.) for simplicity sake. If you had forgotten, it is:
$ cd myhugodirectory
$ hugo server -D -b localhost -p 8080 --disableFastRender
Objectives
- To enable static asset files hosting in the Hugo project.
Create the static folder
Before we start, as specified in the specification, as long we create the static
directory and without altering staticDir
in your config.toml
, Hugo automatically match and create the assets for us. Let's create one using the default settings.
$ mkdir -p static
Create the CSS Folder
Based on the specification, we can see that object inside static folder is map against the base URL. Example:
1. <SITE PROJECT>/static/me.png
is being mapped to <SITE_BASEURL>/me.png
.
Hence, it is better for us to organize the assets properly before it grow into a mess. To do so, let's create a css
folder inside the static folder, so that our css static file is being mapped as:
<SITE PROJECT>/static/css/mycss.css
to<SITE_BASEURL>/css/mycss.css
Here's the command for creating the CSS folder
$ mkdir static/css
Download a CSS
There are many choices of CSS frameworks for you to try it out. However, be on lookout for those that are friendly to Markdown. This is mainly due to the posts and pages in the content
folder are still based on Markdown, not HTML. Once simple and very lightweight CSS I encountered is Kube UI Framework. It's very lightweight, easy to use, and Markdown friendly.
Download a copy of the minimized css version. The filename should be something like this:
kube.min.css
Then, store it inside the css
folder we created. The full path would be:
static/css/kube.min.css
Verify the Serving
Now that the file is serving under css/kube.min.css
. It's time to test it out. Hugo maps the filepath accordingly to the URL. So, our css file is mapped into http://localhost:8080/css/kube.min.css. Visit it and you should be able to see the CSS source codes.
If you see 404, it is most likely the file is misplaced. Try to double check again.
Edit the baseof.html for CSS
Now that we have the css hosted in place. It's time to include it inside our html pages. The easiest way is to edit the baseof.html
master layout. CSS is usually included in the <head>
section of the html.
For Hugo, we include URL using {{ "css/kube.min.css" | absURL }}
tag. This creates the absolute URL with a given relative URL. Since we want http://localhost:8080/css/kube.min.css
, we pass in /css/kube.min.css
as relative path. The BaseURL
is //localhost:8080
.
For absURL
, your link and will alter accordingly based on the given BaseURL
in your config.toml
.
If you want relative URL, use relURL
instead of absURL
.
Let's change the <head>
now:
<head>
<title>{{ block "title" . }}
{{ .Title }} | {{ .Site.Title }}
{{ end }}</title>
<link rel="stylesheet" href="{{ "css/kube.min.css" | absURL }}">
</head>
Once done, Hugo refreshes the page automatically. Otherwise, just do a manual refresh.
You should notice a sharp changes with the text font now. Kube uses roboto instead of the standard font.
Write More
Now that we have our CSS framework linked, you may proceed to write more or edit your layout to demonstrate the site. You can use Lorem Ipsum Generator to create some dummy paragraphs.
If you want to use Markdown as your home page editing, you can proceed to create:
$ hugo new content/_index.md
to create the Markdown content page for home page. Go ahead and edit it. Try out their grid system and structure the content page with some margins.
If you're happy with the styling, you can proceed with the javascript js
inclusion on your own. It's the same procedures as the CSS; the only difference is type type of file.
As far as this guide goes, we had successfully enabled static files hosting in our Hugo repository.