Repository navigation
markdown.headingLinks-aware <AnchorHeading> component
#4273
Replies: 1 comment 3 replies
|
Ah, interesting case. Definitely feels like a more advanced one because, like you said, for most normal users, you would presumably only use If going with an enum-type prop, should there also be a Otherwise, if |
Uh oh!
There was an error while loading. Please reload this page.
What version of
starlightare you using?0.42.6
What is your idea?
Make the
<AnchorHeading>component respect themarkdown.headingLinksconfiguration option by default, and add a newlinkprop (name to be decided later, I just picked something obvious for now) to support the current behavior.The new
linkprop would accept the following values:'auto'(default)markdown.headingLinksis enabled, otherwise renders a basic heading element.'always'markdown.headingLinkssetting. (current behavior)Usage would look like this:
I considered the following alternatives:
markdown.headingLinksby default with a newlinkprop defaulting to'auto'markdown.headingLinksby default with a newlinkprop defaulting to'always'markdown.headingLinkswith no new prop<AnchorHeading>or a basic heading elementThe regression column indicates that a currently supported behavior would no longer be possible.
<AnchorHeading>withmarkdown.headingLinksset tofalsebut provides an easy way to opt into the previous behavior that can be easily documented in the changeset. I also think that this specific case may be a very rare edge case.'auto'in a future release if desired altho I think the breaking change avoided in this case is minimal.markdown.headingLinksis set tofalse.Why is this feature necessary?
The
<AnchorHeading>component is great for Starlight users who want to render an HTML heading element with a clickable anchor link that matches Starlight’s Markdown styles.Altho, for plugin authors, the use of
<AnchorHeading>is less straightforward as most plugins would want to respect the user'smarkdown.headingLinksconfiguration option.To do so, a plugin must:
markdown.headingLinksconfiguration option.<AnchorHeading>in a component that renders either it or a basic heading element depending on the value of the configuration option.Note that I don't consider reading from
'virtual:starlight/user-config'to be a valid solution as it's an internal undocumented module.As of today, I have multiple plugins doing that boilerplate work just to respect the
markdown.headingLinksconfiguration option which is not ideal.Do you have examples of this feature in other projects?
N/A
Participation
All reactions