I like it.

One consideration is that rendering long headings might be ugly, but I feel the increased ease-of-use is worth it. We should definitely be very concise.

One trick could be to keep short title versions in the left side panel and display a more detailed table of content in the homepage with something like this in index.md:

Built-in
- {doc}`builtin/pdrange`
- {doc}`builtin/range`
- {doc}`builtin/pdinterval`
- {doc}`builtin/cfinterval`

```{toctree}
---
caption: Built-in
hidden:
---
integer ranges <builtin/pdrange>
float ranges <builtin/range>
1-coordinate intervals <builtin/pdinterval>
2-coordinates CF intervals <builtin/cfinterval>
```

I kept the "class name" in the headings because we may have duplicates for example, "Intervals with pd.IntervalIndex" and Intervals with CFIntervalIndex`"

I initially thought about grouping PandasIndex[pd.IntervalIndex] / CFIntervalIndex in the same page (same for PandasIndex[pd.RangeIndex] / RangeIndex), but having one page per index might make sense.

One trick could be to keep short title versions in the left side panel and display a more detailed table of content

Clever, I'm definitely a fan of this because I like short titles in the left sidebar. That said, there is not too much currently that these longer titles are a problem, and agree it's much more informative for newcomers.

I also think "Built-in" and "Building Blocks" sections could be merged into a single "Built into Xarray".

Maybe this is also what @benbovy was thinking in addition to a big homepage toc/table, I like subsection indexes. So for example, built-in/index.md where the more descriptive toctree is shown. Something like this https://tutorial.xarray.dev/overview/learning-paths.html

You can set the theme so these subsections are expanded by default

One trick could be to keep short title versions in the left side panel and display a more detailed table of content

good idea indeed!

I also think "Built-in" and "Building Blocks" sections could be merged into a single "Built into Xarray".

I thought this would be good to distinguish, perhaps the index.md will be useful to make that distinction clearly here. I can push an update.

I initially thought about grouping PandasIndex[pd.IntervalIndex] / CFIntervalIndex in the same page (same for PandasIndex[pd.RangeIndex] / RangeIndex), but having one page per index might make sense.

I did too, but I think separating them makes it easier to browse.

built-in/index.md where the more descriptive toctree is shown.

This would mean things like "Built In" and "Earth Sciences" would not be captions anymore. I say we leave that to when we figure how to merge this Gallery with the existing Xarray Gallery.