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

  1. To enable static asset files hosting in the Hugo project.
Hugo - Static Files - Create static folder

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
Hugo - Static Files - Create CSS folder

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
Hugo - Static Files - Download Kube 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
Hugo - Static Files - Verify Files

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.

Hugo - Static Files - use static files

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.

Hugo - Static Files - Write More and See Effect

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.