Nesting Document Categories

[1eyewonder]

Feature Request

I've been using this tool a lot more as of late, and I was curious if the discussion of nesting categories has ever come about.

Using the example structure below

Collections
| -- Overview
| -- Destructuring with Cons
| -- Pattern Matching Lists
| -- Pattern Matching Arrays

I think it would be nice to be able to create nested/subcategories like so.

Collections
| -- Overview
| -- Arrays
    | -- Pattern Matching
| -- Lists
    | -- Destructuring with Cons
    | -- Pattern Matching

My initial thoughts are we could potentially do this one of two ways (I'm sure there are better ideas as well).

1. Special Character Parsing
   We could add some sort of character sequence which would be parsable for category so we know how to nest the folder appropriately.

---
category: Collections -> Lists
---

2. Additional Metadata
   We could add an additional tag such as parentCategory which tells us how to nest the folder appropriately.

---
category: Lists
parentCategory: Collections
---

Notes

• If this is a desired feature, I would be willing to assist/work on this.
• If this would come to pass, I can see people requesting the ability for the UI categories to be collapsible. I would imagine we'd want a way for the user to decide if they wanted the categories opened or closed on startup.

[nojaf]

Hi there,

I have some faint memories of this being requested by someone somewhere.
I don't think I mind this feature but the implementation could be tricky.
Things like the {{fsdocs-next-page-link}} become more complex.
Navigation menus should also be taken into account.

I suppose we do want to be flexible and allow multiple levels of categories.
Not sure yet on the end-user experience.

[github-actions]

🤖 This is an automated response from Repo Assist.

Nested navigation categories would be a great addition! Here's some context on the current design and a feasible implementation path.

Current system: Each .md / .fsx document can declare a category and category-index in its front matter. The sidebar groups documents by category in a flat list.

Proposed approach — use / as a separator in the category field:

---
category: Collections/Lists
category-index: 2
---

This is minimally invasive (no new front-matter keys) and matches conventions in other static site generators. The nesting depth could be limited to two levels (parent/child) to keep the implementation manageable.

What would need to change:

1. Parse category values containing / to extract (parentCategory, childCategory).
2. In the nav rendering code (BuildCommand.fs, around line 770–792), group by parent first, then emit child categories as indented nav items within each parent group.
3. The existing category-index would control ordering within each parent.

The sidebar HTML structure would use nested <ul> elements with a nav-sub-header CSS class for child groups.

If you're willing to work on this, it would be a very welcome PR — and the nav rendering code is reasonably approachable. Happy to help outline the data model changes if useful!

Generated by Repo Assist

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@b87234850bf9664d198f28a02df0f937d0447295. View source at https://github.com/githubnext/agentics/tree/b87234850bf9664d198f28a02df0f937d0447295/workflows/repo-assist.md.

[github-actions]

🤖 This is an automated response from Repo Assist.

I've implemented the nested navigation category feature in a draft PR (branch repo-assist/improve-frontmatter-nestedcat-2026-03-21, created by this run — closes #927).

How to use it:

Add a / separator to the category field in your front matter:

---
category: Collections/Lists
categoryindex: 1
index: 2
---
```

This renders in the sidebar as:

```
Collections           ← parent header
  Arrays              ← sub-header
    - Pattern Matching
  Lists               ← sub-header
    - Destructuring with Cons
    - Pattern Matching

Design choices:

• The / separator was chosen to match Hugo/Docusaurus conventions and the approach suggested in @1eyewonder's original proposal
• Fully backwards compatible — categories without / render identically to today
• One nesting level (parent/child) is supported; deeper nesting can be added later
• Parent category ordering is determined automatically by the minimum categoryindex of any child — no new front-matter key required
• When custom _menu_template.html files are used, the structure is flattened to the parent level so existing templates are unaffected

Generated by Repo Assist · ◷

Generated by Repo Assist · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@d1d884596e62351dd652ae78465885dd32f0dd7d