How to make long sidebars items look better?

[ilg-ul]

I have a C++ project and the reference site is generated by Doxygen. 'm migrating it to Docusaurus, and I encountered an issue with the way the sidebar is rendered.

The original page looks like this:

As it can be seen, the full class names are pretty long, and they do not fit the sidebar. But this is not a problem, since the sidebar is resizeable and I can make it wide enough for the names to fit:

A similar content rendered by Docusaurus looks like this:

The aesthetics are quite debatable, to put it mildly.

First, the sidebar is not resizable, and some names, like the two derived classes at the bottom, cannot be seen at all.

But even more displeasing is the way collapsable items are rendered, wrapped and with the button on the left, not on the right as for regular items.

As usual for Docusaurus sites, the rest of the pages looks quite nice, but for the API Reference sidebar... I'm afraid that the current implementation is not satisfactory... :-(

Any suggestions how to proceed?

[slorber]

Any suggestions how to proceed?

As always, if what the default theme provides is not good enough, you can swizzle.

---

We are open to improving things, but what do you expect us to do?

The best would be to have someone in the community (like you) swizzle our sidebar and show us what a good UX would look like. Then we can learn the lessons on community sites and try to port them to our official theme in a non-disruptive way.

Does this improved UX always makes sense, or is it only relevant for API refs with very long labels and no clear way to break lines properly?

What kind of API do we need to support this?
Does it require us introducing render-specific config per-sidebar?

[ilg-ul]

The best would be to have someone in the community (like you) swizzle our sidebar and show us what a good UX would look like.

Ah, thank you for entrusting me with this endeavour, but web interfaces are not really part of my confort zone.

I might manage to swizzle it, but... I currently don't know how a good UX would look like in this case, and this is why I asked for your expert advice.

I find the current UX generally pretty nice, so I would not change it in a major way, but rather tweak it.

Personally I think we have several small issues.

1 - the arrow button to expand/collapse is at the right of the label. If it were to the left, probably we can arrange for the long text to be truncated, as in the two lines before the last item in the first picture. What solutions do we have to move the button to the left?
2 - the sidebar is not resizable. I have no experience with these CSS details, would adding cursor: ew-resize be enough to do this?

Does this improved UX always makes sense, or is it only relevant for API refs with very long labels and no clear way to break lines properly?
What kind of API do we need to support this?
Does it require us introducing render-specific config per-sidebar?

I think that if we move the button to the left and make the sidebar resizeable, we no longer need a new API to support breaking lines, or to introduce render-specific config per-sidebar.

[slorber]

I currently don't know how a good UX would look like in this case, and this is why I asked for your expert advice.

I'm not either an expert 😅 that's also why Docusaurus theme/design is not progressing much unfortunately.

---

the arrow button to expand/collapse is at the right of the label. If it were to the left, probably we can arrange for the long text to be truncated, as in the two lines before the last item in the first picture. What solutions do we have to move the button to the left?

Changing the place of that button would be quite disruptive for existing sites. Since you are the very first asking for this, I think this should be achieved through swizzling unless there's proven traction for a feature that enables to opt-in for a different collapse button position.

the sidebar is not resizable. I have no experience with these CSS details, would adding cursor: ew-resize be enough to do this?

I don't know, we'd need to create a POC for this and see if the UX is good

But again, would all sites want that resizeable sidebar?

I think that if we move the button to the left and make the sidebar resizeable, we no longer need a new API to support breaking lines, or to introduce render-specific config per-sidebar.

This assumes that all users welcome such changes, which is likely not true.

[ilg-ul]

I tried to add the following to my custom.css:

.theme-doc-sidebar-container {
  cursor: ew-resize;
  resize: horizontal;
  overflow: hidden
}

The definitions are considered, since the cursor changes when hovering over the separating line, but trying to move the line fails, probably some other properties keep the width to a certain value.

Also the overflow property seems to be ignored.

It looks a bit more complicated than expected.

[ilg-ul]

I'm revising my proposal.

The sidebar keeps the actual width, and the button remains on the right, but the label text is rendered truncated, i.e. via the right CSS, if the text is longer than the available space, it is clipped, preferably with an ellipsis ... added at the end (there is a property text-overflow: ellipsis;)

Optionally, the sidebar is resizable, to allow the user to see the clipped text.

I think that neither of these changes break compatibility with existing sites, if the labels are short they do not get clipped, and if the user does not grab the separating line, the resizable sidebar is not noticeable.

I did some experimentation with CSS, and I managed to prevent it rendering the button on the next line, and to clip the text, but my knowledge of CSS is not good enough for a full detailed proposal. :-(