Sidebar folder overview url

[fsimonis]

When generating breadcrumbs for #341, I realized that our Folders don't have a URL assigned to them.

This leads to a missing hierarchy in the breadcrumbs.

Example configuration-xml-reference.html has breadcrumbs Docs > XML Reference as there is no url assigned to the "Configuration" Folder.
It should really have breadcrumbs Docs > Configuration > XML Reference.

suggestion

Consistently add an overview_url: for folders or similar to define such an overview.
Then we can use it in the breadcrumb generation.

[fsimonis]

Today I realized that the GitHub documentation uses folders in there sidebars too.

Each folder has an invisible landing page that lists the content of the folder: https://docs.github.com/en/actions/using-workflows

Could we create something like this automatically? Would it add any value aside from navigation?

[MakisH]

Would it add any value aside from navigation?

Mostly being able to link to a specific section, which is what our overview pages are currently for.

We currently have manual overview pages wherever this makes sense, while the rest of the folders (e.g., basic/advanced configuration) are mostly for keeping the sidebar short. Unless there are SEO reasons, let's not invest any effort here.

[fsimonis]

Unless there are SEO reasons, let's not invest any effort here.

SEO is the only reason for doing this as it gives the site a structure. Currently the entire doc is a flat hierarchy. Having pages for folders would allow add this hierarchy.

I don't see any user-facing outside of potentially (big asterisk) better search results.

[fsimonis]

Unless there are SEO reasons, let's not invest any effort here.

SEO is the only reason for doing this as it gives the site a structure. Currently the entire doc is a flat hierarchy. Having pages for folders would allow add this hierarchy.

I don't see any user-facing improvement outside of potentially (big asterisk) better search results.

[Aayushman-nvm]

SEO is the only reason for doing this as it gives the site a structure. Currently the entire doc is a flat hierarchy. Having pages for folders would allow add this hierarchy.

Adding to the convo, since a migration to Hugo is already planned (#472), this breadcrumb limitation seems more like a structural constraint of the current Jekyll setup.

Hugo models hierarchy natively via directory structure and _index.md, so folder landing pages (e.g. Docs > Configuration > XML Reference) would emerge naturally during migration.

Given that, would it make more sense to address this as part of the migration effort rather than introducing an intermediate overview_url workaround in Jekyll?

Reference doc: https://gohugo.io/content-management/organization/

@MakisH What are your thoughts?

[MakisH]

In the Hugo state (see #979) this is complete: In the local build, http://localhost:1313/docs/configuration/basics/ leads to the following page:

No sidebar entry is highlighted, though. Not sure if this would be easy to address, since there is not always an overview page (cc @MuhammadAashirAslam).