allow for new extra sidebar format that groups h3s into h2s #2020
Conversation
|
Hi @zachdaniel, at first I am 👎 on this particular issue. Previously we were most opening up features we already had internally, but I am worried about adding new features that are specific to the generated documentation case. We already have other mechanisms for grouping and I would suggest exploring them first. FWIW, you told me the reason you didn't break it into several pages was because autocomplete did not work, but perhaps now you can do it and use the extras page grouping, as the autocomplete has been improved. :) |
|
What are the other mechanisms for grouping? As far as I know there is no way to control grouping at the sidebar level. This actually leverages the existing node groups logic in use for grouping module contents in the sidebar, it only makes it accessible to extras by request. I think this is useful in a general sense for larger documents, not just the generated documents. The reason we didn't break it into several pages is not because of the autocomplete, it's because it would be ~50 pages in the sidebar. It isn't an option to have every DSL section be its own document unfortunately. If this isn't accepted it isn't the end of the world, we would just have only the h2's for the sections, but I think it would significantly enhance the browseability of our DSL docs if this was accepted, and could stand to help others with large enough documents. |
Then allowing sidebar groups to be collapsed could be a nice bonus? Plus it would benefit modules and mix tasks tabs as well. |
|
Isn't that what this PR does? |
|
Oh, you mean at the group level. |
|
To me that adds a whole new UI idiom whereas this one reuses an existing UI idiom. It feels more at home given how module sections allow collapsing. |
|
It does also mean more maintenance burden on the generated code side of things. Right now we just manually list each generated file in I really do think that this is applied as a "generally useful" change. I could totally see opting into this change on certain guides that arrange information in a certain way. One of the things you had proposed to me early on in the conversation was to allow indexing up to h3 in autocomplete, and thats exactly what this allows for. Its just that it doesn't make sense to show h2s & h3s as a flat list in the sidebar, so we rely on the existing |
|
My goal would be to index h3 for everyone, not only extras, which is my concern with this approach: h3 getting special behaviour only in pages, while we generally try to keep it consistent and we want to unify it in future refactors. So we don't plan to explore this route for now, thank you! |
|
Bummer. Perhaps I could take on said refactors? Or better yet, I don't actually care about the autocomplete. I'm going to be overriding it myself. So I could keep the autocomplete logic exactly the same and make this only change sidebar appearance? Thanks for your consideration :) |
|
The sidebar appearance is my biggest concern. The autocompletion should always just follow what is on the sidebar. |
For visibility in autocomplete (because sidebar content drives autocomplete), Ash's generated DSL docs have had h2s for each thing someone might search more. My previous PR makes this a non-issue, but as part of exploring solutions to that, it became clear that for certain documents, grouping h3s into collapsable h2s could make for a very nice presentation.
For Ash, we would prefer this presentation even if we are overriding autocomplete.
Old
CleanShot.2025-01-14.at.16.47.11.mp4
New
CleanShot.2025-01-14.at.16.40.52.mp4
EDIT: the new is made possible by us also changing our generated docs to use h3/h2