Hugo best practice theme / modules


In another thread, best forgotten, you mentioned something I think worth a follow-up:

I can’t claim to be a the best at best practices with Hugo: I’m constantly learning new things here, but I think something that would be worthwhile would be to start small; with small single-purpose modules that demonstrate some particular practice and document it well. Get some feedback (obviously posting at least on this forum), and make a pull request for the Docs site.

I think bep (I haven’t @mentioned until we get more concrete) would prefer if we did this in an organized fashion. I know there are efforts, somewhat stalled, to reorganize the site; it’s on my ‘to do’ list to find the GitHub issue or post where the plan is outlined, so that I can contribute to the effort, and I think looking that up and creating a small (just a 2-3 items to start) work plan from that would be a way to ‘get our feet wet’ with this concept.

What do you think?

1 Like

Hi @cshoredaniel,

I believe that a Hugo theme focused on best practices, led by @-bep and @-jmooring, will greatly assist many people in understanding how things may be done better in Hugo. This theme may be used without any other frameworks and is purely focused on Hugo. Those who enjoy creating themes and sharing or selling them can create more particular themes using various technologies such as Tailwind, Bootstrap etc.

This theme can also be used to illustrate sophisticated hugo functionality such as “get remote” and using api’s to get data. Using the get remote and wordpress to json plugins, we can also show how easy it is for Hugo to collect data from a WordPress site. (the method I stated is just what I know there might be better ways).

My idea is that we should establish a bucket that we can fill with expert knowledge over time.


I’ll let bep and jmooring speak for themselves, but I suspect that this is something that if we want to happen, we have to take the initiative rather than trying to argue them into doing. I think it’s also a great way for us to learn Hugo. I’ll probably do some of this on my own anyway, but if you participate I’m more likely to have incentive to bump this up on my priority list (and besides I like to be social for things like this).

If you don’t feel inclined that’s fine, but I think it is the way to make it happen, and also shows that we are taking ownership rather than ‘bike-shedding’ or telling other people what they should work on.

1 Like

Hi @cshoredaniel

I’ve built approximately 100 test projects and numerous customer websites with custom themes in just a few months, but I still lack the professional knowledge for Hugo’s best practice theme. Someone to lead will be required, and I will be able to contribute.

I don’t think many features are required, but rather specifics regarding what is utilized and why, such as utilizing pageref: instead of url: in the menu. Why? What are the advantages and disadvantages of using one over the other?

This will assist in providing answers that are not covered in length in the Hugo documentation and will make more sense because a functioning example will be available. For example, I use pageref: but have no clear explanation for why. A basic theme with only a few key Hugo elements that we can go over in depth will be a huge benefit because there will be fewer puzzled people in the community like myself, and maybe more people will be able to learn and use Hugo with ease.

We can begin by starting a standard Hugo project and working our way up from there.


@pitifi9191 I’ll start with the specific example, but more general comments later (another comment).

  1. Quoting from Hugo Docs for menu entry variables:

    New in 0.86.0

    So the first part of the answer is it requires fairly new Hugo

  2. Further quoting

    Can be set if defined in site config and the menu entry refers to a Page. site.GetPage will be used to do the page lookup.

    So why prefer site.GetPage vs either setting a url or the default of the page’s .RelPermalink if neither is specified?

    1. With site.GetPage you avoid hard-coding the URL as a string. This has benefits if you reorganize your source tree. Since site.GetPage requires a site-unique identifier (which is the path) and errors if the identifier is not found (IIRC) or you have under-specified the identifier (and therefore get multiple matches).
    2. For multilingual sites, GetPage will return the page for the current page’s language. This makes internationalization easier.
    3. GetPage can be used to get a page bundle and with that you get the bundle’s resources. See headless bundle documentation
  3. There is an issue with with .IsMenuCurrent and .HasMenuCurrent that using pageref avoids


1 Like

@pitifi9191 The secret for my rather long answer above is that except for this excerpt:

I got all that information by reading the docs and following the concepts (lookup pageref, then lookup site.GetPage, and also search this forum). Of course, like that excerpt it’s not all new me as I’ve been working with Hugo for a while now and read a great many posts on this forum in the past two years.

I’m willing to do that combination of knowledge and search if you have an organized list of questions that would be applicable to building a theme. I still think if we work on it, and get jmooring, bep, and others to review it would meet the need, and is doable. I also continue to think that starting small is wise. Doing a highly documented theme (with explanation like the above) is a significantly larger project than ‘getting something out the door’, and I would like to get a feel for the process with smaller chunks first.

So, if you would describe an outline of what you think the BPT should have, and pull out a particular piece to start with, I’m happy to work with you on it. We could setup a co-admin ‘organization’ on GitHub to facilitate if it seems to be a going concern, and you were interested.

1 Like


Are you interested in working on this? I’m game if you are.

1 Like

hi @cshoredaniel

i am very much interested and have designed a few screens in sketchapp also prepared some documentation but then got busy with some client work. is it ok if i come back to this after easter.


@pitifi9191 Awesome! No rush. I was just wanting to confirm if we’d moving ahead with it at some point. I look forward to seeing what you have, when you are ready.

Also, doing the notes here instead of DM, so that if others are interested in participating that they are aware of what is up. Can dream, right?

1 Like

Please use DM or your theme/module issue queue/wiki. This is… noisy.