Templating: Compared to Jekyll, I’m completely lost

support
1

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.

2

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
3

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