Node improvements

There are several similar issues on GitHub wanting “more from the Nodes” (the Nodes being the home page, section pages and the taxonomy pages).

I thought it could be good to collect some thoughts on this in a discussion before someone jumps into the source code.

From the top of my head:

  • It should be able to have a Content (md or similar)
  • It should be able to have front matter, with proper Title etc.
  • There should be a way to list all Nodes (and maybe also sort, group and filter them?)
  • ???

I have pulled data for nodes in a kludgy way, so these enhancements would be warmly welcomed.

The question in my mind is, how to link the file to the node - maybe via some kind of a map in a data file?

We should really strive for a naming convention, similar to what we have for layouts. (we have enough settings for people to remember).

So either we create a new top-level content-folder for these (content-node …) or a namespace below content (node or something more sane, configurable for people with sections of that name)):

/content-node/ => home page

I like /content/node/whatever because you already put content there. My two cents is it is easy to remember, for me at least. :slight_smile:

I’ve been thinking about just following the convention of creating the content where you want it to appear.

/content/ => home page
/content/categories/hugo/ => Hugo's category page

I do worry though that this is short sighted and missing some important things.

1 Like

As we have to be able to map it to the section nodes etc., it cannot be totally random.

As to mixing them with other content-files, the only real problem I see is naming conflicts. Having reserved is fine and dandy (although I suspect someone out there already have content files with that name), but then it’s content files for the nodes with other names. We currently have the 404, but there will be others (I hope).

And in my eyes these are two different sets of content:

  1. Editorial stuff (blog articles)
  2. Presentation related content

Keeping them totally separate will have additional benifits. One could, as one example, imagine the presentation content coming from the theme.

How about pre-fixing node content with % e.g. content/%home/

I could see “index” conflicting with someone trying to create an E-book site. What about using “_node”? Hugo uses underscore-prefixed items already (ie. _default for layouts).

/content/ => home page
/content/categories/hugo/ => Hugo category page
/content/division/department/ => Department of Division page

The odds of _node conflicting with someone’s pathing is pretty slim, I think. Another option:

On Feature Ideas

One feature to add to the wishlist with Node front-matter: ability set a default “type” for children. We are contemplating migrating a large site to Hugo. Our initial brainstorm was to layout our content like this:


Since some units/departments may have their own layout, we were thinking that each content page would have a type in their frontmatter to identify the layout to use. If we could set it in the Node front-matter, we wouldn’t have to litter the content files with extra front-matter.

For me there is quite a distinction between content (creating a page) and content within nodes. Maybe that is because I am used to this being called blocks.

In my mind it should be really separated due to the pre-processing effect of a page .md would be very different to a node.

So my initial view is:

  .. /node/(everything here is a node or sub folder)
  .. /page/(everything here is a page or sub-folder)

This would mean content/page folder is the equivalent to current content folder is how Hugo preocesses it.

I think this would also make it easier for newcomers to better see the difference between pages and nodes.

The challenge with this is that a page has no single parent, so you would have to pick one. Is it the section or a taxonomy …?

I was thinking of section parents, since the main motivator for me was selecting a layout template based upon the type. When I said “type,” I meant the explicit type in the front-matter (Page.contentType).

I’m not against sending taxonomy items downstream from a Node, but that’s not the feature I was talking about.

If we intend to send items downstream from the Section/Node to the Pages, would it make sense to put them in a separate front-matter section so that a Section could use taxonomies without forcing inheritance onto the children? For example, use this structure in a Node content file:

title = "Special Title"

  type = "special"
  tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
  categories = [

The inheritance thingy sounds like a *second iteration" or something … The special syntax sounds funky. I think it should work like it does in the object oriented world: The most specific value wins.

I have thought about this a little, and concluded that most of the “problems” with this gets much easier once we agree that a page is just a page that is just a … page…

And that a Node is just a Page with a discriminator.


  • Today’s pages are Page with discriminator “page”
  • Homepage is Page with discriminator “home” or whatever
  • Taxonomies are Pages with discriminator “taxonomy”

They have some structural differences (pagination etc.), but they are basically just pages.

With that in mind we can put them all in one collection and add query filters on discriminator:

  • .Site.Pages: filtered by discriminator = ‘page’
    *.Site.All: No filter
  • where: when the sequence is Pages add discriminator = ‘page’, but let user override

Enough tools for users to shoot themselves in the foot in the above, but plenty flexible.

/cc @spf13

1 Like

I like this idea a lot. I’m trying to think through all of the implications of this change and in particular how this would work with mapping content files to a node and to a template in a logical way.

Would this approach also work with markdown content for a section list?

Let’s assume the following content

  • content/blog/
  • content/blog/post-1/
  • content/blog/post-2/

And those layout files

  • layouts/section/blog.html
  • layouts/blog/single.html


  1. Can the content from content/blog/ be accessible in layouts/section/blog.html? (I’m currently using some funky hacks)
  2. How do we ensure that the content/blog/ isn’t included in .Data.Pages of layouts/section/blog.html?

I hope it’s clear what I’m trying to do…

Yes. This will be

{{ .Content }}

In blog.html

The .Data.Pages will work like my .Site.Pages in the example above. They will be filtered by discriminator “page” – the blog section page will have discriminator “section” (or whatever), and hence excluded … But .Data.Pages in sections is probably already only containing the children of that section … Never mind.

Hi, new hugo user perspective here.

I found that it is nearly impossible to build a very simple static site with a few top level pages that could still be edited by a non-tec user. just imagine a very simple site like this:


NO folders, no subdiretories (in content) nothing else, very simple. Of course the user should be able to edit the index.html frontpage and add another page if she likes and the menu should be generated automatically.

This is nearly impossiible to build with Hugo because of limiting assumptions. OK, maybe not impossible, but I did not find a clean way to build a result that still will be understandable for end users.

Instead I have to use hacky config elements - e.g. uglyURLs = true - why this option has even remotely anything to do with the fact that subfolders are used or not is not understandable. Also at some point I had a “.html” file in the public folder generated, I do not clearly remember what caused this - I then found after a few hours the github issue with the workaround for editing index.html. OK, and now create a menu - of course the menu from the documentation did not work, well, maybe because I did not follow hugo assumptions and just putting five md files in content breaks eveything, sigh.
I stopped there and did not even look into how to integrate gulp or webpack - what of course should be integrated out of the box in any way, not left to the user as another workload.

Please understand me - I am not ranting (ok, a liitle bit maybe), I am trying to make you understand that you are creating a much too limiting set of assumptions with this piece of software and it leads to the situation that the most simple default usecase does not work.

Please while developing new versions of your node concept always try to also test for the simplest and most easiest use case: a user that just creates max. ten top level pages in /content - no directories, sections, types or whatever. SOme images and a little bit of css and js in ONE top level folder like e.g. “assets” - and of course an autogenerated menu from this. Very simple, too simple for Hugo as it is now. But this is the “default” use case for thousands of mini-personal-websites that do not need wordpress for that - and still this is too complicated with Hugo. The features that are already there are very nice to have, but to build the simplest sites it gets too complicated for most of users out there.

It would be great if Hugo made zero assumptions about how to organize content, but still allow the strong organizational features for advanced usage.

Thanks for your attention!

Many, me included, would say that the assumptions is what make Hugo great. It is hard to create a product that is great for everyone.



Please don’t hijack an existing thread.


There is a workaround for your use case that is shorter and simpler than the comment you’ve added to this thread.

  1. Create a content directory called “singles”
  2. In your config, set permalink for singles to “/:title/” so that the pretty URL is from the root
  3. Each single page will default, templating wise, to /layouts/_default/single.html
  4. If you want individual layouts for each top-level page, just reference type and layout in the front matter for each page and then create the corresponding layout in layouts/singles/yourpagelayout.html

Check out the docs for more extensive instructions or alternative approaches. Cheers.

1 Like