Templating: Compared to Jekyll, I’m completely lost

Here’s what I don’t quite get:

File structure

With Jekyll it’s easy: one directory for every layout.

This would work:

layouts:
  default.html
  doc.html
  empty.html
  post.html
  single.html

Great. Now… how do I get that for Hugo?

What’s the most basic

Inheritance

With Jekyll, I define what layout I want to use in the frontmatter. I think for the index page index.html is automatically chosen.

_layouts:
  index.html
  . . .

For Hugo, what’s my index? On one of the themes, it’s baseof.html?

layouts:
  _default:
    baseof.html

Is that really it? It’s defined in layouts/_default? Does that like override something?

I just can’t find a simple example that properly explains how this templating works in action. The docs weren’t the greatest help.

There are different layout lookup orders depending on the type of content. The Homepage lookup order starts with layouts/index.html.

You don’t need a base template. That’s an “advanced” feature.

Thanks for giving Hugo a shot.

PS - The docs site I’m linking to is a new docs concept site. Hoping it will replace the current production docs site soon. If the docs are lacking, please help us make them better.

1 Like

Hugo Templating Structure

Hi @onlinemantas - I’ve built a lot of Jekyll and Hugo sites. While Jekyll’s templating is easier to understand, Hugo’s allows for a great deal of complexity should you need it.

While I can only speak about how I’ve used them, here are a couple of thoughts to start you on your way.

Where Jekyll has default.html Hugo has _default/baseof.html where you would put your basic site structure.

There are two other templates that handle a lot of heavy lifting:

  1. _default/list.html This is where you’d put your logic for listing content from a particular section.

  2. _default/single.html This is where you’d put your content for a single page

You can override those for a particular section by adding section templates to your layouts folder.

So, if you have a “section” (“collection,” in Jekyll) called “post” you would create a folder called “post” and within that folder put a template called single.html that will override the default single (_default/single.html).

You can also put various “views” for the post section in that folder, but that’s another topic.

To override the list template for the “post” section, you’d add a template for it in a “section” folder: section/post.html.

As @moorereason said, the home page is merely the index.html template in your layouts folder.

I know coming from Jekyll this may seem a bit overly complicated, but these inheritance rules allow for robust theming and complex sites with some enforced consistency.

Here’s a link a post with links to a theme I built to help someone get started, and maybe playing with that will help (might be easiest to clone the demo repo)

That’s a start. The docs are good, but can still be overwhelming. Take it a little farther and see what questions you come up with

1 Like