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:

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.

[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).

[NightMachinery]

How's the state of multi-level sections support in 2021?

[pedromorgan]

mkdocs is easier.. Stuff the speed.. i want its to be less painful et all..

Hugo was good at the start.. hit a sweet spot, but now is a different beast

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.