I would like to create a blog site using Hugo on Windows 10. I have Hugo installed and it seems to be working okay. I need a little advice on how to set everything up though, as I’m new to Hugo, markdown and running a blog site.
I do have experience with using HTML and CSS to create a website manually.
I would like to organise the site similar to this:-
example.com/index.html = home page
example.com/about.html = about page
example.com/contact.html = contact page
example.com/category1/index.html = list of posts in category1
example.com/category1/post1.html = 1st post in category1
example.com/category1/post2.html = 2nd post in category1
example.com/category1/index.html = list of posts in category2
example.com/category2/post1.html = 1st post in category2
example.com/category2/post2.html = 2nd post in category2
…and so on. Obviously those aren’t the actual category and post names, but hopefully you see what I have in mind.
On each post page, I would like the option of showing links to related posts that may or may not be in the same category. I’m not sure what options there are for that.
The terms “types”, “sections”, “categories” and “tags” in the documentation are confusing me a little. It seems that sections are intended for different types of content (i.e. posts vs images), rather than similar content on different subjects, unless I have that wrong. Categories and tags seem to be a way of differentiating content for index pages, but don’t seem to change where the content ends up on the finished site.
Can anyone offer advice or point me to some tutorials?
The best way is to just make a new site and start playing around with it.
Don’t worry about types right now, but sections are just a way of structuring your content files. Check out the quick start; in it you create a blog post, in the posts section. So all your posts go into that directory.
Say you wanted to put up short stories, you could make a new section called fiction, and then you can style it differently, or whatever. That is the thing to know about sections.
Taxonomies (categories and tags) are added to a piece of content via its front matter. You don’t add the pages for them, they will create list pages for ya automatically.
These are oversimplifications, but it ought to get you started. Just poke around in the docs a whole bunch, and it will start to click.
Hugo does not support related posts out of the box. There have been discussions about it but it has not been realized yet. However there are several solutions in the forum.
For example I have slightly modified a snippet that I found at the topic: Using intersect to find related content to render related content based on tags (instead of a custom parameter).
Here is the working code (it goes in single.html)
{{ $page_link := .Permalink }}
{{ $tags := .Params.tags }}
{{ range .Site.Pages }}
{{ $page := . }}
{{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }}
{{ if and $has_common_tags (ne $page_link $page.Permalink) }}
<---- html here ---->
{{ end }}
{{ end }}
As said above, you can use the sections (folders in the /content/ directory) to be different types or categories… What this signifies is which front-matter/markdown archetype will be used went creating a new post in that section. Also, without changing the permalink, in the website it will say the section name in the address after the domain. However, there is also a taxonomy (way of classification) called Categories, which are like top-level containers. They aren’t folders but they aren’t tags, they are more like a super tag or a meta-folder. So you can put what category a post is in the front-matter and then a page (like the index.html) would list out all the pages in that category. You could also change the permalink (address for the post) to be something like /:category/:slug/ or something like that, which is different from the default /:section/:slug/ that is used. The slug here is the url-version of the title of the post unless a specific slug is given in that page’s front matter… meaning it can be different that the filename or title of the post.
I’m not experienced enough to say which one is a better path to follow but I would like to hear other opinions.
Does anyone know the advantages and disadvantages of the two organisation methods (using sections vs using categories)?
I can see that putting all posts in the posts directory and using categories to place the finished pages in different directories on the site would mean that you couldn’t have two markdown files of the same name and you’d have to add extra front matter for each post, but I can’t see any other obvious differences.
Is one more efficient than the other? Is one better for listing links to the newest posts on the home page?
What do people usually do (or wish they had done) to plan ahead for when there are hundreds of posts? For example, if you only post once or twice a week, it seems a little pointless to have listing pages for each month, but having one for each year would mean they would be too long.
Really think about that, because if you aren’t used to use taxonomies in other instances (like a content management system, or Wikipedia), then it can be confusing when you first start using them.
As far as I can tell, there are no differences between taxonomies in Hugo, so tags and categories are treated the same; they happen to be popular names for taxonomies in other software, and can have subtle differences between each other.
Hugo creates categories and tags by default, so you can add them to front matter and they will work, but you can also define your own, like the Actors and Directors examples in the docs.
They are completely arbitrary, but if you need a default way of thinking about them:
Categories are topics your site covers. If you have a blog, they can be different subjects you blog about, like writing and gaming, two different areas that may interest folks. If you had a documentation site, they could be different aspects of a software project, like configuration and tips.
Tags are contextual links between content. So you can have a blog post in the gaming category, while it is tagged Guild Wars 2 and MMO. If you have a doc in the configuration category, you might tag it Unix and plugin.
It takes a while to grok, and you have to see how others use it to see all the ways it is useful. And also when it isn’t used.
If I were you, I would stick with a single section, plus your static pages (like about and contact). And then use categories to either link to category pages that list the content, or list other posts from that same category at the bottom of your posts, something like that.
If you keep it simple and understand what is happening, you’ll know how to build on top of that structure.
I think I understand the difference between categories and tags now, even though many sites use them in different ways.
What I’m not certain about is why it might be better to use a category definition in the front matter to tell Hugo where to build a page rather than putting the markdown files in different directories to tell it the same thing. It seems like extra work for me and Hugo for no obvious benefit. Unless Hugo needs categories and tags to be used together for some reason or it treats different sections as being completely different?
Having looked at how other people have organised their sites has made me realise what I definitely don’t want on my site:-
The date or the words “categories” or “tags” in the URL
as @maiki described, the terms tags and categories are just default but arbitrary. You could make tags act like categories and categories act like tags. Or not use either of them or only one of them, or make 100 more classifications (taxonomies). Doesn’t really matter.
Regarding your structure question, if you have different folders in your /content/ directory, each folder’s name will be the /(folder name)/blog-post-title/ in the address. So if you’d rather do that you and not use … categories for example… you can. This way in your mental model of your site, the content structure matches the website structure.
As you are starting off, I recommend doing that. Make content folders based on what will go in them (blog, essay, tutorial) and you can tag them for contextual relations and keeping track what what’s in the posts.
Okay, I’ll do a little experimenting over the next few days. One thing I would like to try is creating directories inside the post directory and then removing “post” from the URL in the site configuration file.
How do people handle linking to older posts? In six months time I don’t want to be uploading a dozen listing files every time I add one new post, but I do want visitors to be able to find older content.
Okay, no more freebies, just read all the docs and you should have all your questions answered (and if not, you can ask them, get the answers and put them in the docs).
Having a look at it will give you one way to construct your posts’ archive based on dates and utilizing Hugo taxonomies.
Hint: you don’t have to display the end result as an actual calendar, you can modify this partial and call it in your template even as a simple list of months -or whatever else you want-.
maiki: I have looked at the pagination docs, but didn’t see any mention of producing archives automatically. Most online blogging software has that feature by default, but it seems you have to set it up manually in Hugo.
Unless I’m missing something, the docs only mention splitting index listing pages based on how many links there are per page.
If you had 100 posts in a category, and 10 links per page, there would be 10 listing pages. Adding one more post would make it 11 and all 11 would need to be uploaded to the online site as they will all have changed.
I was wondering how people avoid this. I have seen some Wordpress sites where older listing pages are organised by date, which would solve the problem as older listing pages would not be updated once they reached a certain age. i.e. a june-2017 listing page would not contain links to posts written in July of this year, so that would not need to be uploaded again unless there was a sitewide change made.
onedrawingperday: That looks a little more complicated than I was hoping for, but will give it a try if I cannot find a simpler way.
I dont’ know where they are but there are other posts here in the forum that show how to range through the pages and only select pages within certain dates. But I can’t imagine a way to automate it for making the ones you want to no longer change… other than manually making a new archive page for each time period you want to group together and be static. The constantly updating list page you can have it only select posts up to a certain date from the build date so any pages outside of that would not be added to the list. If you wanted, maybe there is a way to set that day to something like… 6 months ago or something, and then each month you have to manually create a new page that will populate only with those month’s posts. It’s work, but I think it can be done. I can’t tell you how exactly, some good searching on the forum here for date related lists or archives would be good.
You might want to subscribe to the issue about date-based archives in Hugo, but it doesn’t currently exist. A database makes that easy, hence it being a “feature” in other software.
Hmm. I’m now wondering if taxonomies would help with this.
If I thought of the site as being like a magazine, I could use a taxonomy term of “issue” and set a numeric value for that in the front matter of each post. That way I could potentially have monthly, bimonthly, quarterly or yearly back issues (archives), depending on how often I end up adding new content.
