Previously I completed a basic Hugo install with the Blackburn theme. The default site structure contains a directory to store the various pages:
/content/post/
We can create subdirectories within \post
to suit our needs and organise content, and that is fine. However, you may be tempted to create additional directories at the same level as \post
, in which case you will need to delve into Hugo’s inner workings. In this article we will expand our site hierarchy to include an additional directory called news
and link to it from the menu. In Hugo lingo, this is called a Section.
First we create the new directory. This will be the name of our new section:
mkdir /content/news
Then we edit
config.yaml
and copy the existing menu section ofpost
:[[menu.main]] name = "Posts" pre = "<i class='fa fa-list fa-fw'></i>" weight = 1 identifier = "post" url = "/post/"
Paste the copied section and edit the
name
,identifier
, andurl
parameters to point to thenews
directory:[[menu.main]] name = "News" pre = "<i class='fa fa-list fa-fw'></i>" weight = 1 identifier = "news" url = "/news/"
The
weight
parameter determines the order the menu items are rendered. If there are multiple items with the same weight, they will be sorted alphabetically.The
pre
parameter contains the icon to display,fa-list
. Check out http://fontawesome.io/icons/ for many, many more icon options.Don’t forget to create at least one page in the
news
directory:hugo new news/my-news.md
Now start the Hugo local server
hugo server --theme=blackburn-master --buildDrafts
Browse to
http://localhost:1313
. You should see the News link in the left menu. But clicking on it gives a blank page. Or worse, an error like404 page not found
. What happened?
Add the new directory to the theme
What we’re missing is an index page for \news
, similar to the one \post
has. Lets dig into the blackburn-master
theme and look at the \layouts\indexes
directory. This directory has a single file post.html
.
Create a copy called
news.html
:cd \Hugo\Sites\codeooze\themes\blackburn-master\layouts\indexes copy post.html news.html
Restart the Hugo local server
hugo server --theme=blackburn-master --buildDrafts
Browse to
http://localhost:1313
.
The News link should now resolve to a page containing a list of all pages in the /content/news/
directory.
Modify the home page
There’s one thing left to do. Browse back to the home page at http://localhost:1313
and you may notice something missing. The new page we created, content\news\my-news.md
is not listed on the home page. Worry not:
Navigate to
\themes\blackburn-master\layouts
and editindex.html
. You should see something like this around line 9:{{ range ( .Paginate (where .Data.Pages "Type" "post")).Pages }}
We want to show all pages, so modify the line:
{{ range ( .Paginate (where .Data.Pages "Section" "!=" "")).Pages }}
This will list all pages inside subdirectories of
/content/
on the home page. Pages in the root directory, like/content/about.md
, will not be listed.Restart the Hugo local server and browse to
http://localhost:1313
. The page we created inside/content/news
should now be listed.
Next steps
There are of course many other customisations you can make in Hugo and to your theme. As an exercise take a look at the following files and compare the differences:
\themes\blackburn-master\layouts\post\single.html
\themes\blackburn-master\layouts\_default\single.html
Notice the same differences when viewing news.html
and post.html
? Hugo will use templates in the _default
folder when we haven’t provided an alternative layout to use. If you want all content pages to render the same as post.html
, simply copy the first file over the second one.
Alternatively, to customise just the news.html
page, create a new directory:
cd \themes\blackburn-master\layouts
mkdir news
Then create the file single.html
to suit your needs.
Happy organising!