Theme: Keeping identical templates and archetypes in sync

1

I want my theme to be general enough that it just works out-of-the-box for basic functions. For example, for the archive page, I would like these four common structures to just work:

  • content/archive.md
  • content/archives.md
  • content/archive/index.md
  • content/archives/index.md

I figure there is only one way to allow a single template to be used for all these cases, which would be to create:

  • themes/mythemename/layouts/_default/archive.html
  • themes/mythemename/layouts/_default/archives.html
  • themes/mythemename/layouts/content/archive/list.html
  • themes/mythemename/layouts/archives/list.html

If I can do this with a single, or just two files, my question is how to do that. If I can’t, my question is if I can somehow source one of the files in the other files in order to keep the content the same when I update the master file.

I’m also curious of whether it seems like a good idea, considering that most themes I’ve seen has a very limited layouts folder.

Telling the user that if they want an archive, they have to create content/archive.md or it won’t work seems like on the one hand putting too much restrictions on the user and on the other, makes the theme require the user to read through the readme even for tasks that should work out-of-the-box. But of course, the theme gets more complex this way, which might be a negative, and it obviously only covers the four cases I’ve managed to think of and so is still not completely general.

I would like to do the same thing for the blog, which shouldn’t have to be named content/post/. blog and posts are also obvious things to call it, so it seems I should allow for these cases too. In this case, having several archetypes is also relevant.

2

My search-fu wasn’t at its best yesterday, it seems.

This thread raises, among other things, the same issue as me concerning that sections need to have predetermined names for themes to work.

@CREwert asks what the users of themes should expect sections to be named. I, on my end, am asking what I should expect users to expect my theme to require.

For now, I think I’ll go with soft linked folders named blog, post and posts under layout for the blog, and likewise for the four versions of archives I listed.

I noticed that my theme broke when I defined taxonomies in the plural in the site config, since I had used the singular in a template. Here, at least, I think I will only have to check for “tag” and “tags” and it should be covered.

3

In an ideal world there should be no expectations but flexibility.

Theme authors are encouraged to use the mainSections method and to avoid hardcoding section names in a theme’s templates.

mainSections is an internal Hugo method. Sections with most pages are auto-detected and it needs zero configuration. Furthermore one can easily filter out for example pages of a specific type.

Actually no. You can create one template under layouts/archive.html and then in the front matter of the _index.md call it with layout = "archive"

So basically if the user needs an archive they can call it via the front-matter of any content file.

Keep it simple.

See:

1 Like