[toc] when showing the toc for the first time, show it expanded instead of collapsed

[Melandel]

Checklist

• [x] I searched the :help documentation using / for helpful information
• [x] I have read the frequently asked questions
• [x] I did not find any similar issues in the issue tracker
• [x] I prefer making an issue instead of using discussions, Matrix or Telegram

Addition or change Currently, when shower the toc (table of content), it appears collapsed.

In terms of user experience, the reason why a user would explicitly send the command to show the toc is more than likely to be that they want to see the toc without an additional click or mapping.

For that reason, I think it would be a good and cheap improvement to show it expanded the first time, and store that state if the user decides to hide the toc then show it again (because their reason is most likely visual-only)

Alternatives considered

• creating a setting for configuring the collapsed/expanded status of toc when displayed (default status)
• creating a setting for configuring the collapsed/expanded status of toc when displayed (complex, conditional, regex-based)
• creating an action for toggling the collapsed/expanded status of toc instead of relying on follow mode (allows for user-defined mapping including that action)

[Jelmerro]

That's a good thing to consider, I'm a bit undecided on which states should be remembered or not, ideally it should all be settings, but doing that conditionally seems a bit much, so I might just add one for open/closed by default, and then remember/sync the state of the toc across pages (based on settings, so either open/closed or active/disabled) or something. What do you think is the best option here?

[Melandel]

I would go incrementally in order to find as best as possible the sweet spot between usefulness and complexity.

For the first iteration, I personally would go without setting, ie always expand when going from hidden to shown.

Then we can learn through users' feedback whether more configurability is needed - as well as whether or not the feature is known/used

From that feedback we can infer the real use of that feature, and how far we want to go in order to make it configurable.

That's obviously just my personal opinion!

[Jelmerro]

Well, that actually sounds very logical and much simpler in terms of implementation. However, I would like to have the TOC there by default on the help page, but not expanded, because it would cover a lot of the page, just shown there to let people know that it exists, but maybe that's actually not needed or too much. Now I'm reconsidering making the TOC the default for the help page, or if it should just be hidden like now and have no close toggle at all, just open=shown and closed=hidden.

[Melandel]

I would like to have the TOC there by default on the help page, but not expanded, because it would cover a lot of the page, just shown there to let people know that it exists

I see your point.

The help page starts with a few bullet points mentionning "essential keys".

Would it be fair to have the very first bullet point be about how gc toggles the TOC?

it should just be hidden like now and have no close toggle at all, just open=shown and closed=hidden.

Come to think of it, it does make sense.

I would add that, ideally, when going from closed/hidden to opened/shown:

1. showing the toc at the same location as last time it was shown may be interesting (in particular when the toc is so long there is a vertical scroll)
2. tracking the currently displayed portion of the document at all times (using a color for the matching line in the toc for example) seems like a great idea. With this idea may come the idea of having a button to "display toc centered around currently displayed portion of the document")

We probably don't need to go that far in the toc features, though. I'm writing them down here mainly so I don't forget 👍

[Jelmerro]

Alright I've decided to just revert the upcoming breaking change of showing the toc by default, I'll add it to the help page more clearly, but leave the tocpages as is, and start work on making it always open as the actual breaking change, for now without extra scroll features, but those are nice to haves.

[Jelmerro]

Actually, I might just add it to the cheatsheet instead of changing the intro text, I'm quite happy with how that fits neatly on first run and isn't filled with all these extra features, but just the basics. People will find it if they want it, and if not they'll ask for it and I'll tell them how it works, same for any other feature I guess.

[Jelmerro]

Implemented in 11.0.0 :tada: