Expectations, documentation and dividing Hugo into 'core' and 'web-builder'


I am proposing to explicitly (with a multi-year transition period) to divide Hugo into ‘core’ (the part I see as being like Make+GCC or the Go compiler) and ‘web-builder’ subprojects.


The purpose of the hugo binary

As I commented on another user’s post, I think of Hugo as being like Make+GCC rather than a website builder per se, but seems there are many users who expect Hugo to be a drop-in website builder.

The Technical context

Mixing things like internal templates and ‘starter’ websites into a ‘make/compiler-like’ tool seems to me to be mixing content with the tools that build the content. In addition, things like internal templates have a greater frequency for need for changes to meet the current web environment than a build tool itself.

I think it would help the ‘core’ developers to separate concerns and focus on build tool development as a different exercise than template or ‘starter’ development.

Further, no templates or ‘starters’ are going to meet all user’s needs, and deal with that takes time away from tool development.

The social context (negative approach)

A number of those users have had what I feel is a very negative, even hostile approach the Hugo project as it now, and comments like

make me wonder if this part of a campaign for what I would term a ‘hostile fork’ of the project.

Hugo of course is open source and folks are free to do what they wish with the code as long as they abide by the license terms, but the part that bothers me is that it ‘feels’ like an effort to discredit and/or take over the great work of folks like @bep, rather than an effort to improve how the Hugo project and/or community is organized.

The social context (docs & desire to build websites by non-developers)

Despite the warnings when one first logs into the forum

there seem to be many folks expecting a more ‘WordPress’-like experience.

In addition, I think the Hugo docs are a great reference, but for non-developers learning Hugo from the docs can be a challenge. In addition, ‘the interwebs’ are full of blogs posts and themes that are based on, or use, very old versions of Hugo and contain information that is out-of-date, not best practice, or outright wrong. So there is a valid need for docs that are helpful for new, non-developer, users.


External Resources

There are of course folks like CloudCannon, Netlify, and sever others, who are making things like CMS frontends for Hugo and the new book ‘Hugo in Action’ mentioned elsewhere on this forum.

Community & Developer Time & Resources

Developing good new-user documentation takes a great deal of time and effort, and is probably best done by community members who are closer in skill-sets to the types of users targeted by the documentation. Further, the ‘core’ developers are busy developing Hugo.

It is not clear that there are enough accurately knowledgeable community members of the right skill-sets who would work on this.

Would Need a Framework to Work In


Should separating the build tools from scaffolding, starter templates, and end-user / new-use documentation be deemed desirable, those who would be working on the ‘web-builder’ vs ‘build tool’ aspects would need both technical and organizational structure to be able to work effectively.


There would need to be some discussion of the proposed ‘web-builder’ framework and how it would be organized in terms of repos, building, and in general “what’s in, and what’s not”. There would also need to be an initial framework developed to get things started.


This could be a ‘sibling’ project to ‘gohugoio’. That would make it easier (IMO) to give collaborator access to ‘web-builder’ contributors / developers than if it were part of the ‘build tool’ organization. There would also have to be some thought to how collaborators get added/removed, decision making, etc, since I imagine this part is going to pull in more folks than the ‘build tool’ part, and therefore is more likely to have more ‘office politics’ to deal with.

Offer to Be Point on This

If there is an interest in this, I am willing to offer myself (or support someone else who I trust to do a good job of it) as ‘point’ on this.

In many ways, if this is a separate ‘organization’ it doesn’t require permission from the current Hugo core, but I’d only want to do this if there were ‘buy in’ from folks like @bep, @jmooring, @davidsneighbour, @zwbetz, etc, so I wonder if they and others could comment on their thoughts and willingness to support such an endeavor.


I know this is long, but I hope it makes some kind of sense, and folks consider it a worthwhile concept to pursue.

1 Like

Why don’t they then just use … WordPress?

The thing is, in a large population there will always be different needs and expectations. I agree that hugo new site leaves lot to be desired, but I’m not sure making it into a different binary will solve much (other than more confused users asking what to install? “So if I want to build web sites I need the builder and to build the web sites I built with the builder I need hugo-core, is that right?”

What’s missing with hugo new now is, in my head, some templating support, e.g. “project scheletons” (which certainly should live outside of “hugo core”).

I personally have a set of things I want Hugo to do better, and the above is not currently in my “top 5”, but that may change.


That’s actually more along the lines of what I was thinking of…divesting the actual skeletons and internal templates from core, but not the logic that uses them. Sorry for not being more clear on that.

@bep In terms of ‘web-builder’ I didn’t mean that as another binary, but as a ‘project’ that lives outside core and takes care that kind of thing so you (and anyone who joins in on the tooling in the future) doesn’t have to.

1 Like

Somebody (you?) recently wrote, that Hugo is more like a make tool than a CMS for websites. And as such I think the task of making “onboarding” easy is in the hands of the theme developer. Each theme should have a theme-template repo that (for instance on Github) can be forked without history to get started with a new website, containing all the setup required.

As in Hugo is the knife, not the chef, hugo is the car, not the driver.

For WordPress, what you are trying to achieve is something like the block manager they recently introduced. As opposed to people having work on the template files.

I don’t think there are enough resources for support/documentation, even if that would be feasible on the developers side (which it also isn’t yet). As an external project it would require people that understand Golang and Hugo good enough to be able to contribute, and then their time would be spent better on improving Hugo.

We need to clone Bep :wink:

@bep not sure how i got on this thread but i can answer this.

we can use any framework or implementation for websites. almost no bounds. yet we typically do not build custom sites, because most of running a site isn’t custom and is modularizable.

we use wordpress bc it’s best balance between control and roi. most people who use wordpress don’t think or talk about roi, they say ease of use. [will stop talking about wordpress bc you seem to have a non-wordpress-centric view of things, which is good from an efficiency standpoint)

i disagree with poster that hugo is some sort of make-like compiler. hugo does little to no grammer validation of anything you input to it (outside of toml files). it does transform directories of files from some content into another, so perhaps that is what OP is focusing on. but there’s very little quality control or anything comparable that a compiler would have that hugo offers (since hugo has pipelines, perhaps these things could be added and so perhaps the OP is referring to thinking about hugo more as a meta-compiler or a pipeline framework. i don’t feel this is accurate but in terms of his metaphor it might be tighter fit to say hugo is closer to llvm than it is to say clang, and to represent this in the code so that other people could know how to hook clang-like front-end ontop of hugo). he may or may not be saying that and to me that is overly complicated.

i will go back to the original post i created (and that the OP referenced in creating this ticket), and build on that and your own point that people should contribute more to hugo itself. which would be easier if you spent a few minutes creating a graphic or two that synopsises the hugo content-to-content process. this would ideally make it easier for both developers to contribute and for users to onboard (which helps bring in developers, and adds to positive feedback loop).

anyways, seems like you’re closer than the OP has stated or suggested. coding details will get worked out by you and any PRs you take. the key is to get more and better PRs, which is [mostly] why I opened the discussion OP is trying to build off of. [will bow out any future discussion from OP, since he tried to hijack my thread to talk about compilers that i don’t feel are directly relevant to my post or increasing adoption]

btw, we are tech agnostic so we use anything. we are not consumer facing so we mostly don’t invest a lot in our web front ends. currently using wordpress, but have used all of: wordpress, adobe xd, mobirise, custom sites, google sites, and more. have looked at hugo many many times, it seems closer than ever.

i love that more templating support and project skeletons (which sounds like your more flexiable implementation of auto-creating skeletons w/hugo-build??) is on your mind.

you might also want to think about- if only as a questioning exercise… what if wordpress ran ontop of hugo? while i don’t agree with the OP’s characterizations- I think this is closer to the question that he’s trying to ask.

anyways, as i’ve stated repeatedly thanks again for your efforts. totally willing to put in some time to create a couple of high-level user and developer graphics that can be included anywhere to facilitate onboarding both types.



Wordpress can easily run in the background of static website generators. For instance Gatsby has an integration for that.

This basically illustrates, that a static website generator doesn’t have to do the job of a CMS. It takes content of whatever form and “makes” a website out of it.

“Wordpress can easily run in the background of static website generators. For instance Gatsby has an integration for that.”

yes, good point as for years [and still] we presently generate a static site using wordpress as a backend.

all above comments are with this as a given.

I think it helps to remember that

  • Hugo has very little restrictions on what you can build. There are some boundaries (sections, taxonomies etc.), but in general you can build whatever you please.
  • This becomes a challenge for theme creators, course.
  • Wordpress have a much more confined set of rules, which makes it easier to approach from a “web builder” perspective.

My main take about the above would be that Hugo isn’t currently WordPress, and I kind of like that. There will at any point in time be about 1000 different web frameworks, and it’s a good thing that they do different things.


I apologize for starting this thread in the first place. I was frustrated by the amount of negative opinions being advanced, and when folks like @bdpp ‘come on strong’ and then blow off explanations they don’t like (their rudeness combined with the ‘bad actor’ situation, and my own tendency to be paranoid got me concerned about motivations) I wanted to have something I could do to help improve the situation.

@bep I appreciate all your great work, and I’m sorry this thread took up some of you valuable time.

[aside] One clarification I would like to make, is that the reason for a ‘sibling’ or ‘child’ project suggestion was the very flexibility you mention. ‘child’ might be a better term, and hopefully there would be more than just one. In a sense a really good theme project would fit, but I find most themes developers aren’t all that active on this forum, and it’s not clear (to me) how much they are in tune with best practices and so on, and/or keeping up with Hugo development.[/aside]

In any event I’m happy enough to contribute as I can. As @davidsneighbour points out there is challenge in any new project related to Hugo of having community-minded folks with the knowledge, time, and energy to make it work.


Hi @cshoredaniel,

I want to say thanks for taking the time to share your thoughts in detail. I’ve read it several times but I lack the necessary expertise. However, I’m extremely interested in becoming a part of a Hugo best practice theme that can serve as an example of Hugo’s best practices.

For instance, instead of url, use pageref: (it is just a simpler example, but I am sure you get what I mean). This can make it easier for theme developers to adhere to recommended practices, and Hugo newbies like myself can learn from the example theme or use it to build a website.


Hi @bep

If you had a GitHub project with upcoming features at the concept stage, it would be fantastic. This could pique people’s interest and excitement even more.


1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.