Hugo: Multi-level sections (tree)

[rahul286]

@spf13 Sorry in advance if you find this too long or absurd (or both).

This requests is based heavily on personal needs. I am struggling with this problem from long time. So I decided today to post this down in as much details as possible.

I came across few threads in same direction suggesting to make use of front-matters. I will explain why I think front-matters is not an optimal choice here.

Problem

I have created a sample site to explain this problem - https://github.com/rahul286/hugo-sample

Content looks like:

$ tree content
content
├── level-one
│   ├── level-two
│   │   ├── level-three
│   │   │   ├── level-four
│   │   │   │   ├── page-4-a.md
│   │   │   │   ├── page-4-b.md
│   │   │   │   └── page-4-c.md
│   │   │   ├── page-3-a.md
│   │   │   ├── page-3-b.md
│   │   │   └── page-3-c.md
│   │   ├── page-2-a.md
│   │   ├── page-2-b.md
│   │   └── page-2-c.md
│   ├── page-1-a.md
│   ├── page-1-b.md
│   └── page-1-c.md
└── page-top.md

4 directories, 13 files

As you can see there many levels at which directories and content are present.

Expected Output

What I am trying to have is...

For any folder, list down pages at immediate levels only OR at all levels.

If listing at all-levels, nested lists should be created. Something like list of pages shows on - http://rtcamp.com/tutorials/

As you can see for sample-site - http://rahul286.com/hugo-sample/level-one/ shows all pages but without any hierarchy.

At sub-levels nothing shows up: (bigger problem)

1. http://rahul286.com/hugo-sample/level-one/level-two/
2. http://rahul286.com/hugo-sample/level-one/level-two/level-three/
3. http://rahul286.com/hugo-sample/level-one/level-two/level-three/level-four/

But direct link to inner-page still works - http://rahul286.com/hugo-sample/level-one/level-two/level-three/level-four/page-4-b/

This means directory structure is preserved. Just nested directories do not have an automatically generated index page.

Hugo did generate index page for top-level folder automatically as it appears - http://rahul286.com/hugo-sample/level-one/ (source - https://github.com/rahul286/hugo-sample/blob/gh-pages/level-one/index.html )

Workaround/Ideas

I think hugo has few things already in-place which generated level-one index page.

Few changes/enhancements will be needed so hugo can be used on sites with multi-level pages.

• [ ] Extend index generation logic to any directory. May be _default/list.html template can be applied to sub-directories.
• [ ] Provide some filter and meta-data so we can control listing itself.

I think first task will be easier _(sorry if I am underestimating this, as I'm new to golang)_

Second task can get tricky as different sites may wish to control list pages html differently.

1. List all pages, subpages and subdir. Like linux tree command at that page-level. Live example, this section on one of our site: https://rtcamp.com/tutorials/ and https://rtcamp.com/tutorials/ , https://rtcamp.com/tutorials/mail/ , https://rtcamp.com/tutorials/mail/server/ and https://rtcamp.com/tutorials/mail/server/testing/ - at each level we are only showing subtree
2. List all pages if there are no subdirectories present. May be some sites wish to show list of "immediate pages" and sub-directories only. Reason could be - there may be 1000+ pages and if we show entire tree at top-most level, it may makes top-page cluttered.
3. In both cases above, there could be things like listing pages and sub-directories separately. Using ul/li v/s ol/li v/s something else in output html.

At code-level, hugo may extend...

.Data.Pages Variable

{{ range .Data.Pages }} may have few variants like:

{{ range .Data.Pages.SubPages }} - for immediate subpages (.Data.Pages already have all subpages i.e. entire tree)

{{ range .Data.Pages.SubDirs }} - for immediate subdirectories

{{ range .Data.Pages.SubDirsAll }} - for all subdirectories (nested)

May be we can make use of new where clause as below:

`{{ range where .Data.Pages "Level" 1 }}

`{{ range where .Data.Pages "type" "dir" }}

`{{ range where .Data.Pages "type" "page" }}

Or may be group by:

{{ range .Data.Pages.GroupBy "type" "page" }}

Node variables

We may introduce some additional node variables.

For example:

.SubPagesCount - Number of subpages this
.NumLevels - Number of subdir levels
.HasSubDirs - true if current node has subdirs

Why I am not using fornt-matters?

Finally, let me add my own explanation for not using front-matters for this.

As site grows, new levels gets added for better organization. It may be needed to move pages in bulk from one-section to another-section at no-fixed-level. So if we make use of front-matters and menus, we may need to manually update each page during such moves.

While I like power of front-matters, I prefer to avoid it whenever possible. If tree-like structure can be achieved by conventional file-system hierarchy, it may reduce clutter in actual content. Also, for a contributor it will be easy to find write article on local filesystem.

Finally

Thanks for reading. :-)

Please correct/improve this wherever possible.

[oskarrough]

@rahul286 thanks for the write-up. This is exactly what my project needs. Would be great to automatically create a site navigation based on the content structure.

[vjeantet]

Don't know if it's relevant but I built a website with 5 sub levels of contents, thanks to Menus features and the PullRequest #1271

[oskarrough]

@vjeantet great - are you able to share your solution somehow?

[vjeantet]

ok my current usage can not be published, but i'll blogpost an example, i'll post it here when it's available.

[vjeantet]

Here is an example
http://vjeantet.github.io/hugo-menu-show/

And source code
https://github.com/vjeantet/hugo-menu-show

[rhewitt22]

Interested to see where this goes. For reference here is @spf13 pseudo code/implementation strategy from ~ 1 year ago.

[uncledent]

Hello everyone, is there already a solution available? I have the same problem with category/subcategory empty page. Some news on this issue?

[baruchlubinsky]

I've made a small change here:

https://github.com/spf13/hugo/compare/master...baruchlubinsky:master

That at least gives an index page at each level of content. With .Data.Pages containing just the list of the current level. The list template may be provided at layouts/section/level1/level2.html.

This is satisfactory for my needs, I'll try to take a deeper look and create a proper pull request.

[staropram]

Any plans to merge baruchlubinsky's patch? Or commit to implementing this feature?

[bep]

Any plans to merge baruchlubinsky's patch? Or commit to implementing this feature?

It will happen eventually. I'm not merging any "patches" that is not in the form of a proper pull request (but I can say that the mentioned patch is too limited).

[staropram]

Thanks for the response. And thanks for the great work on hugo!

[vimdude]

@bep I need this feature and I'm willing to implement the feature this week as described by @rahul286 , plus he didn't mention pagination. Just want to make sure the requirement makes sense as it is or any changes before I implement.

[pedromorgan]

Ok so this is the showstopper for me. Ie a per section navigation

[tryjigs]

@pedromorgan After trying to implement this feature as mentioned last week, I found in the code a hidden feature in hugo with categories. If you create categories like the following:

categories:
 - level-one
 - level-one/level-two
 - level-one/level-two/level-three
 - level-one/level-two/level-three/level-four

hugo will create index on all those levels (and pagination works if you enable it). That's an alternative to patch from @baruchlubinsky . Categories, you can fix them in the template. The only problem you end up using /categories/ ... unless you move the content manually using a script to main and replace /categories/ everywhere.

Note: my content is auto generated and not manually by hand.

[vassudanagunta]

The more important thing is simply to support subsections with their own _index pages, and the ability to optionally list only immediate children, but it would also be nice if the Which Template will be rendered? logic is correspondingly updated so that a templates defined at a more specific level overrides templates defined at more general levels.

In other words, Which Template will be rendered? would be updated as follows. My additions are in bold, and ideally could be expressed in a simpler way for the documentation.

• /layouts/TYPE/LAYOUT.html
• /layouts/SECTION-SUBSECTION/SUBSECTION/LAYOUT.html
• /layouts/SECTION/SUBSECTION/LAYOUT.html
• /layouts/SECTION/LAYOUT.html
• /layouts/TYPE/single.html
• /layouts/SECTION/[SUBSECTION/SUBSECTION/single.html
• /layouts/SECTION/SUBSECTION/single.html
• /layouts/SECTION/single.html
• /layouts/_default/single.html
• /themes/THEME/layouts/TYPE/LAYOUT.html
• /themes/THEME/layouts/SECTION/[SUBSECTION/SUBSECTION/LAYOUT.html
• /themes/THEME/layouts/SECTION/SUBSECTION/LAYOUT.html
• /themes/THEME/layouts/SECTION/LAYOUT.html
• /themes/THEME/layouts/TYPE/single.html
• /themes/THEME/layouts/SECTION/[SUBSECTION/SUBSECTION/single.html
• /themes/THEME/layouts/SECTION/SUBSECTION/single.html
• /themes/THEME/layouts/SECTION/single.html
• /themes/THEME/layouts/_default/single.html

[bademux]

@tryjigs using taxonomy for hierarchical structuring is the best solution here.

• One can structure content with multiple hierarchies
• The same content can be placed into more then one term in taxonomy

In my opinion subsections is pretty straightforward implementation, but it has no flexibility comparing to hierarchical terms in taxonomy.

And I have a question about current "hierarchical terms in taxonomy" state:
Is it possible to query parent\children category?

[bep]

And I have a question about current "hierarchical terms in taxonomy" state:
Is it possible to query parent\children category?

Please use http://discuss.gohugo.io/ for questions/troubleshooting. Also see Hugo Documentation.

[kakawait]

@bademux

And I have a question about current "hierarchical terms in taxonomy" state:
Is it possible to query parent\children category?

I did it by using a big monstrous trick (so don't blame about code) that you can find here https://github.com/kakawait/hugo-tranquilpeak-theme/tree/master/layouts/partials/internal and result https://tranquilpeak.kakawait.com/categories/

But as @bep said please open questions on http://discuss.gohugo.io/ and do not continue discussion on that issue

[acnebs]

I'd just like to add an addendum to this: when Hugo gets multi-level support, I'd like to be able to have one template for when I want to list subsections, and one template for when I want to display/list actual content/summaries of content.

My suggestion would be to make a new reserved template, called subsection.html (or some other, better name), ala list.html, single.html, etc. This would then work like so:

/layouts/<SECTION>/list.html would then be the template to show either all sub-dirs of <SECTION>, or all content files in the tree, the user could choose.
/layouts/<SECTION>/subsection.html would then be the template for all subdirectory/subsection listings.

The idea behind this being that if I have 10 subsections in the same section, it's likely that I'd want to be able to have all 10 subsections share the same templates, rather than go with the current paradigm, which seems like it would be to have a /<SECTION>/<SUBSECTION>/list.html for each subsection.

This way, you'd only need two template files to have a structure like so, with listings at each level:

/animals/
/animals/dogs/
/animals/dogs/poodles/
/animals/cats/
/animals/cats/persians/

etc.

[gbmhunter]

For what it's worth, I added this functionality on my blog also. You can see the hierarchal menu structure at https://blog.mbedded.ninja/ in black on the left-hand side. The code which generated the menu is based on the directory/file structure of the content and can be found in the file https://github.com/gbmhunter/blog/blob/master/layouts/partials/menu.html (also check out menu_recursive.html, which this calls).