Anchor Links for Headings

[at-the-vr]

What version of starlight are you using?

0.13.0

What is your idea?

Now that Astro Docs have anchor links for headings I wonder if Starlight can also use the same anchor links (in similar way how Astro Docs PR #5610 went )

Why is this feature necessary?

• tad bit quicker way to share starlight references across Astro Lounge

Do you have examples of this feature in other projects?

• Astro Docs 😁

Participation

• I am willing to submit a pull request for this feature.
• Removing the PR participation as of 21 December 2023 UTC 9:23 AM

[HiDeoo]

As someone who really like heading links, definitely an interesting idea 👍

I know the current approach has been to not try to ship a lot of remark/rehype plugins by default but maybe this could now be revisited as an official or community Starlight plugin.

I guess there would still be a need to support multiple behaviors for the link rendering as I assume not everyone would want to use the after behavior or the same SVGs. Altho, getting accessiblity right for these anchor links can be tricky and at the moment, it looks like the after and wrap ones are the only ones that are really properly accessible so maybe only those two could be supported.

In the meantime, for anyone interested in this, for the after behavior, the PR from Chris is definitely an excellent reference to look at. For the wrap behavior, I've created a small guide to quickly get started with it.

[delucis]

We can definitely consider porting it from docs to Starlight! Has some tricky i18n stuff too if we use the same pattern as docs, because the links need to have accessible labels like “Section titled <HEADING_TEXT>”, so making it built-in (potentially with an opt-out like headingLinks: false or something) could make sense.

I’d honestly even say we could just pick one accessible strategy and ship it as an opinionated “this works trust us” solution and if people want something else they could disable and implement their own using rehype plugins.

One final consideration would be eventually supporting all our features in Markdoc too. Doesn’t have to block this though: I think something similar is probably do-able via their config.

[kevinzunigacuellar]

Starlight knows what's right for your docs 😉

I love the idea of shipping a set of remark/rehype plugins by default and having a config option to disable them. Even Astro md/mdx support have their own set of default plugins so I don't see why starlight can't have one.

[delucis]

Yup, I agree. The only restriction is that I do think we should aim to support Markdoc as well, so should try to aim for stuff that can also be built without remark/rehype if possible.

[dionysuzx]

+1 would love this feature because sharing specific areas of the documentation is very useful.

[dionysuzx]

FYI now i learned i can still share without the hover anchor by clicking the sidebar, which is okay, but some users might take a while to learn that behavior.

on the other hand it's arguably more accessible. i think both is nice.

[alkasm]

By default, you only get H1, H2, and H3 in the sidebar, so doesn't fully solve the problem.

[delucis]

Heads up that I just opened a draft PR to add anchor links!

#3033

[delucis]

Forgot to close this — we shipped this feature in v0.34! 🚀

See https://astro.build/blog/starlight-034/#heading-anchor-links for details.