Markdown Math Support + Inline Equations not working

[trueberryless]

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.

[HiDeoo]

Starlight is built on top of Astro which supports adding third-party Markdown plugins for Markdown and MDX.

In your case, you should be able to use remark-math and rehype-mathjax to render the mathematical equations with a configuration looking to something close to this:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import remarkMath from 'remark-math';
import rehypeMathjax from 'rehype-mathjax';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeMathjax],
  },
});

Some related links:

• Astro docs regarding markdown plugins: https://docs.astro.build/en/guides/markdown-content/#markdown-plugins
• remark-math example with MathJax support: https://github.com/remarkjs/remark-math#example-mathjax

[trueberryless]

Thank you very much!

[trueberryless]

Okay, it works fine, installation worked great.
However I stummbled across a problem:

Inline math equations are not working:

Does anyone know about this issue or why it's occuring?

[trueberryless]

I tried probably all different kind of syntaxes available:

- \(\Delta t\)
- $\Delta t$
- $$\Delta t$$
- ...

I cannot even remember what I tried else...

Do I maybe need some kind of JS in the tag?

[trueberryless]

I mean it seems to get that I want an inline equation but it just doesn't render right...?

[HiDeoo]

When you say:

Inline math equations are not working

With this image:

Does this mean it should render something totally different or just that it's not rendering properly (multiple lines)?

I am not a user of these plugins but could it be a CSS conflict? Could these plugins require some extra CSS to be loaded?

[trueberryless]

I just shouldn't render with multiple lines.

It could really be something with CSS, but I am not familiar with how CSS is working in Astro. I'm actually completely new to JS Frameworks in general...

[HiDeoo]

Thinking more about it, I think it may be due to the CSS applied to the markdown content by Starlight itself in

starlight/packages/starlight/components/MarkdownContent.astro

Lines 47 to 51 in 7837825

	.content :global(:is(img, picture, video, canvas, svg, iframe):not(:where(.not-content *))) {
	display: block;
	max-width: 100%;
	height: auto;
	}

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).

[trueberryless]

Okay, I added custom CSS now, by following the steps described here: https://starlight.astro.build/guides/css-and-tailwind/

And then I overrode the CSS rule (!important to make sure it's overridden - but you probably already know that 😉)
I will probably try to find a better selection method cause this is kinda awkward...

.math-inline svg {
    display: inline !important;
}

Now it looks like this:

Thank you for this suggestion! How did you find this CSS rule? Did you look in browser dev tools or searched manually in starlight? But without being at a computer? Respect, dude!

However, this is more or less a temporary fix and I'm not planning on keeping this solution, so I would really appreciate if this issue will be fixed sooner or later...

Therefore, I won't close this issue right now. Maybe someone else will see this issue and fix it. Summing up, thank you guys!

[HiDeoo]

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 👍

[trueberryless]

There is only one more thing to consider before implementing a solution for this issue which I found today:

The table of content should also include inline equations because, although this heading has a math equation as you can see here:

This $\Delta t$ does neither show up in the "On this page" section nor in the URL:

I think, the theoretical solution for the table of content is pretty trivial because you can just add the symbols as SVGs exactly the same as in the text. However, in the URL it's different because you can't just but a SVG there. Therefore, and ideas are very welcome here!

[delucis]

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 withastro/astro#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

[robmunger]

I found another example of where some of Starlight's CSS interferes with embedded math.

The relevant CSS is:

.sl-markdown-content
	:not(a, strong, em, del, span, input, code)
	+ :not(a, strong, em, del, span, input, code, :where(.not-content *)) {
	margin-top: 1rem;}

Starlight seems to be applying a 1rem top margin to the HTML elements of my equation, causing the vertical spacing to be dramatically distorted (it should look like a regular fraction rather than being stretched out).

I'm using MathJax with the CommonHTML output format. As you can see in the upper-right of the screenshot, with this output method, MathJax outputs custom elements. I presume that because they are contained in markdown content, sl-markdown-content is applied to them, blowing up their upper margin.

I suspect trueberryless didn't have this issue because they were using the SVG output method (MathJax uses HTML output by default, but rehype-mathjax uses SVG by default). I imagine a solution similar to the one trueberryless used could be applied to fix this, though there may be many elements to apply it to, so I don't know if it would work.

I'm not requesting any changes. I'm just sharing my findings. Thank you for your wonderful work on this theme!

[delucis]

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.