Automatic folder index in README?

[alisman]

First, great job on this project and thank you.

Gitbook (yuck) has a feature where if a README doesn't exist for a folder, it will generate a landing page with an index of links to the pages in that folder. This is rather nice. I am wondering if there is a way in Retype to create this kind of an index and embed it in a given landing page.

Gitbook annoyingly gets rid of the index if you actually provide a README. So there's no way to put some copy above the index, which is actually important.

[geoffreymcgill]

Hi @alisman. Thanks for the feature request.

Over time I've gone back and forth on whether we should include this functionality in Retype. In general, I find how GitBook implemented their index pages a tad annoying, so that has always turned me off adding the same feature.

There are certainly times where having an index of pages internal to the folder would be useful, but as you pointed out, there's no way to add custom content to the pages in GitBook.

More often than not, I would rather not have an index summary page.

On the Retype website, we have one (here), and I regularly flip-flop on whether it's actually useful. Personally, when I click on the Components folder, I would like the folder to expand and show the sub-menu items. Then I expect to click the content page I'd like to view. At least that's how I would expect it to work with the current Retype left navigation component implementation.

Clicking the Components menu item and having it open a summary page feels like an unnecessary step.

Let's call this summary of all pages within a folder a Folder Table of Contents (FToC).

My thoughts are:

1. Typically, I do not want an index page in my folders
2. If I do want an index page, I typically do not want a FToC
3. If I do want a FToC, I want some control over how and where it is rendered
4. I would like the option to place custom content above the FToC, and/or
5. I would like the option to customize precisely where the FToC is rendered on the page, below or above or within my custom content

In Retype, the Tag summary pages (see retype.com/tags/) are auto-generated when you set the tags page config and the FToC pages could be generated in a similar way.

Retype already has the ability to add custom content to the /tags summary page by you just adding your own /tags/index.md page. Categories works exactly the same too.

Retype will automatically add the summary cards below your custom content. To demonstrate, I added a custom /tags/index.md page, see retype.com/tags/.

The source for the custom /tags summary page is available at https://github.com/retypeapp/retype/blob/main/tags/index.md.

Each individual tag has it's own summary page too, see https://retype.com/tags/guide/.

So, the point here being, we could easily do something similar to the /tags/guide/ with the folder table of content summary pages. Essentially all the functionality and internal pipelines to render those summary cards are already built.

Personally, I would not want the FToC to be generated automatically for each folder as I feel this should be an opt-in decision.

We could add an optional configuration to the Page. I have no idea what that would be called. Need to think about it.

Another option could be a Project level config where you could turn on automatic FToC index page generation. By default, I would vote this would be false (turned off).

Another option could be a new component like [!ftoc] (<-- terrible name, just demonstrating) and you could place that anywhere within your .md page. The [!ftoc] would be replaced with the page cards, something like:

It would also be very nice to have options for different card layouts. Instead of stacked cards, maybe a grid with the feature image above the page title + summary. It wouldn't take much for us to implement that option either.

Anyways, sorry for the wall of text.

Hope this helps.