Multi-level nested pages handling [feature-request] #465

rahul286 opened this Issue Sep 2, 2014 · 8 comments


None yet

9 participants

rahul286 commented Sep 2, 2014

@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.


I have created a sample site to explain this problem -

Content looks like:

$ tree content
├── level-one
│   ├── level-two
│   │   ├── level-three
│   │   │   ├── level-four
│   │   │   │   ├──
│   │   │   │   ├──
│   │   │   │   └──
│   │   │   ├──
│   │   │   ├──
│   │   │   └──
│   │   ├──
│   │   ├──
│   │   └──
│   ├──
│   ├──
│   └──

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 -

As you can see for sample-site - shows all pages but without any hierarchy.

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


But direct link to inner-page still works -

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 - (source - )


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: and , , and - 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.


Thanks for reading. :-)

Please correct/improve this wherever possible.

@spf13 spf13 added the enhancement label Sep 2, 2014
@spf13 spf13 added this to the v0.13 milestone Oct 19, 2014
@spf13 spf13 self-assigned this Oct 19, 2014
@spf13 spf13 modified the milestone: v0.13, v0.14 Feb 22, 2015

@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.


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


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


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

@anthonyfok anthonyfok modified the milestone: v0.15, v0.14 Sep 16, 2015

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

@bep bep referenced this issue Nov 9, 2015

In-Page Pagination #1560

@anthonyfok anthonyfok modified the milestone: v0.16, v0.15 Nov 30, 2015

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

@moorereason moorereason modified the milestone: future, v0.16 May 7, 2016

I've made a small change here:


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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment