starlight: Markdown Math Support + Inline Equations not working

What version of starlight are you using?

0.9.1

What is your idea?

Support for mathematical equations like this one: $\lim_{x \to \infty} {1 \over x }$. I think MathJax is a JS library which supports all mathematical equations.

Why is this feature necessary?

I need to document some math on my website and many other users would probably benefit from it…

Do you have examples of this feature in other projects?

  • GitHub: $\sqrt{x^3}$

Participation

  • I am willing to submit a pull request for this issue.

About this issue

  • Original URL
  • State: closed
  • Created 3 years ago
  • Comments: 15 (13 by maintainers)

Most upvoted comments

Just note I had to add

.MathJax svg {
	display: inline !important;
}

to global.css to fix it

Thanks for the follow-up, good to know we have identified the issue and have a temporary workaround (and no magic there, I just knew Starlight added CSS to the markdown content and in which file so I opened it on my tablet and scrolled until I saw SVG ^^)

Good call on not closing the issue, we can now take the time to investigate the generated markup and figure out what would be the best approach to handle this case 👍

Thinking more about it, I think it may be due to the CSS applied to the markdown content by Starlight itself in https://github.com/withastro/starlight/blob/783782560770d35b3996c390b4c1d976e99d7f8b/packages/starlight/components/MarkdownContent.astro#L47-L51

This basically enforces a display: block; on all SVGs in markdown which could explain the screenshot. I am not at a computer right now so I can not investigate more but maybe if this plugin supports passing custom CSS classes to the generated HTML, you could pass down the not-content class to avoid hitting this rule.

If this is not a supported behavior, I guess you could add your own custom CSS to overwrite the rules applied by Starlight by targeting element with the math or math-inline classes.

If you have no luck with these 2 ideas, do not hesitate to comment so I can take a look when I get back to a computer (or if someone else figure it out before).

Thanks for sharing @robmunger! Does the library you are using provide a way to add a class name to the base element of each diagram? If so, adding not-content should help here. Good feedback though, definitely something people run into from time to time which is good to know about whenever we’re thinking about our styling setup.

Hmm, the table of contents issue is trickier. Astro handles headings extraction for us, so would need to be fixed upstream rather than in Starlight itself.

It’s a bit similar to https://github.com/withastro/astro/issues/8240, which is about MDX expressions in headings (e.g. ## Heading with {expression}). It’s quite tricky because currently Astro only provides a text string for headings, not HTML, so I don’t know if it would be able to provide the SVG in this case. Does seem to be something Astro might need to think further on as Starlight is showing quite a few use cases where smarter heading extraction would be nice.

Closing this issue for now as I don’t think we can fix this in Starlight itself. I would encourage people who are interested in improving support here to check out Astro’s headings plugin though to see if we can work out a way to improve this upstream: https://github.com/withastro/astro/blob/main/packages/markdown/remark/src/rehype-collect-headings.ts