add option to skip rendering child when rendering ToC

[jamescarr28]

What’s changed

We have added an optional flag for the multi_page_table_of_contents/render_page_tree helper functions. The table of contents (ToC) currently has limitations when using layouts to group sections and create filtered ToC - e.g. when using header_links and requiring a specific ToC .

Example usage

<% section_index_page = sitemap.resources.find {|resource| resource.path == "section/index.html" } %>
<% content_for :sidebar do %>
   <%= render_page_tree [section_index_page], current_page, config, yield, include_child_resources: false %>
<% end %>

<% wrap_layout :core do %>
  <%= yield %>
  <% content_for(:toc_module, "in-page-navigation") %>
<% end %>

Identifying a user need

This is particularly an issue when we have a directory with an index page, and then sub directories containing nested sections. When trying to organise this structure using header_links to create sections, we want each section to create it's own ToC eg:

source/
├── index.html                   
├── contact.html
├── section/ # this is the link used in the `header_links` href
  └── index.html
       ├── sub-section/
           ├── index.html 
           ├── subpage1.html     
           ├── subpage2.html

The expected result would be:

This bug has been previously raised here. We are currently unable to publish updated public facing documentation due to the navigation being too painful. This fix allows us to do this, while maintaining backwards compatibility

Existing options that don't generate the right result

Using resource.children

If we use the resource.children call then we loose the section index page altogether. This page can only be found by clicking the link in the navigation (top right). This is a confusing user journey and very unclear.

code example:

<% section_index_page = sitemap.resources.find {|resource| resource.path == "section/index.html" } %> # using a parent resource creates issues similar to those outlined below, and doesn't solve the problem
....
 <%= render_page_tree section_index_page.children, current_page, config, yield %>

Including resource in tree builder

If we try to include the the extra resource then the full child tree is rendered below the main section. Result below is the same if we merge into a single array etc

code example:

<%= render_page_tree [section_index_page], current_page, config, yield %>
 <%= render_page_tree section_index_page.children, current_page, config, yield %>

result:

Using single page ToC

When using the single page ToC functions the ToC changes when you move to a different page, with the section index missing altogether

<%= single_page_table_of_contents(yield) %>
<%= render_page_tree section_index_page.children, current_page, config, yield %>

[huwd]

So the code looks good to me, @NathanD-GDS you raised the initial bug, you wanna give this a look too?

[claire-cheuk]

Looks good!

Needs final approval from Huw and Nathan before merging

[NathanD-GDS]

Looks good - just a few small suggestions.

[NathanD-GDS]

Suggested change

	This gem has helper functions to render your ToC. You should use:
	This gem has helper functions to render your ToC. You can use:

Is it 'should' or 'can'?

[jamescarr28]

Interesting question, it depends on how much leeway we want the gem to have I guess. I'd say that it's should as we're saying, 'if you want to [create a single page table of contents], you should use [the function] as we've tested it and approved it works in the style we expect'