Inline Styling for rehype-mathjax

tani commented 1 month ago

Initial checklist

[X] I read the support docs
[X] I read the contributing guide
[X] I agree to follow the code of conduct
[X] I searched issues and couldn’t find anything (or linked relevant results below)

Problem

In HTML, the appearance of the style element in the body element is undesirable from a specification point of view. Historically, there was a time when the appearance of the style element in the body element was tacitly accepted, but the WHATWG specification, which is currently the main HTML specification, concludes that it is undesirable for the style element to appear in the body element. https://github.com/whatwg/html/issues/1605

Solution

By muddling through and assigning the appropriate stylesheet to the style attribute of each element, you can properly format formulas without style elements: walk around according to the stylesheet selector and assign rules to the style attribute of matching formula elements in the form style="...". This method is successful in SVG. On the other hand, it does not succeed with CHTML. This is because in the style sheet for CHTML there are rules starting with @ to define fonts. Against this background, we propose to add the following new option.

{ stylesheet: { insertType: 'internal' | 'inline' | 'none' | null | undefined }

'internal': markup using style element
'inline': markup using style attribute
'none': do not insert stylesheet. (to be inserted manually to strictly follow WHATWG in CHTML)
null | undefined : same as 'internal'. Default.

Already ready for pull requests. As soon as the discussion here is complete, we will move on to work on the pull request. Tests have been added and coverage is 100%.

https://github.com/tani/remark-math/tree/inline-css

Alternatives

Existing code confirms that there was awareness of the problem, and if the head element is in the syntax tree, the style element is inserted into the head element instead of adding a style element under body, to comply with the WHATWG specification. Our proposed improvements are in the same direction as this policy and follow it when the internal option is enable.

wooorm commented 1 month ago

Can you clarify what, in that very long issue, which itself is not the spec, you are referring too?

wooorm commented 1 month ago

Why do you propose changes here, and not in mathjax? Why not use a different tool, that does what you wan, such as a different renderer, or KateX?

tani commented 1 month ago

The main issue here is that the style element is being embedded within the body element, which is problematic.

Could you clarify which specific part of that lengthy issue, which isn't itself the specification, you are referring to?

The issue mentioned above discusses a proposal to allow the style element to be placed within the body element. However, this proposal was rejected in the issue's conclusion. Therefore, placing the style element within the body element is still discouraged. The proposal to include it in the specification refers to the conclusion that it should not be included in the specification.

For those who prefer a quick summary, the reason why the style element within the body is not recommended by the specification can be found here: HTML5 Validator Results

Moreover: https://html.spec.whatwg.org/multipage/semantics.html#the-style-element

4.2.6 The style element ... Where metadata content is expected. In a noscript element that is a child of a head element.

Why are you proposing changes here and not in MathJax?

I determined that this is an issue with rehype-mathjax, not with MathJax itself. Here’s a step-by-step explanation:

MathJax is a library that outputs both mathematical expressions and CSS, which is then embedded into HTML. This process can be divided into two parts:

Generating the mathematical expressions and CSS.
Embedding the generated expressions and CSS into the HTML.

MathJax correctly implements part 2 by adding the CSS to the head element. So, when using MathJax alone, there’s no issue with the specifications.

This library was initially implemented by me, Tani, and donated to this project. You can see this mentioned at the bottom of the README. The program I created only used part 1 of MathJax and implemented part 2 specifically for rehype. Even now, this library follows that same basic method.

When embedding the generated expressions and CSS (part 2), if the proper place (i.e., the head element) is not present in the document tree, the CSS gets embedded next to the element. This has been the case since I initially implemented it, but it was a mistake because it results in HTML that is not recommended. As stated earlier, this generates non-recommended HTML.

Since part 2 is independently implemented by rehype-mathjax, proposing this issue in the main MathJax project would be incorrect. Therefore, I’ve submitted the issue here.

Why not use a different tool that does what you want, such as a different renderer or KaTeX?

There are three reasons for this:

It’s possible to ignore the non-recommended HTML generated by this library and use another one, but that doesn’t change the fact that this library has an issue (generating non-recommended HTML). Therefore, raising the issue is justified.
KaTeX and MathJax serve the same purpose of rendering mathematical expressions, but they support different types of formulas. MathJax supports bussproofs, while KaTeX does not. This provides a reason to continue using MathJax.
KaTeX doesn’t have a feature to generate CSS in the first place. You can find this information in the README. CSS needs to be specified with a link element. This feature corresponds to the "none" proposal mentioned above, which is an option that behaves like KaTeX.

wooorm commented 1 month ago

The issue mentioned above discusses a proposal to allow the style element to be placed within the body element. However, this proposal was rejected in the issue's conclusion. Therefore, placing the style element within the body element is still discouraged.

I do not think this reasoning is correct. You are quoting an issue which is 8 years old, posted in the context of scoping things, and is related to what conformance checkers should recommend. It was closed years ago. Perhaps new things happened since. Importantly, as Dominic mentions 2 posts below:

Also, just to be very clear: this entire issue is not about changing browser behavior. The spec already requires, and browsers already implement, processing for <style> in body. It works, albeit with the negative effects I discussed above.

The rest of the issue is, from what I gather, also discussing whether style in body is that negative: anything has trade offs of course, but apparently people are doing it very often, so apparently there are good reasons.

Where metadata content is expected.

Indeed, that says it is allowed. You can also read about the body element in the spec, and see that it can include “flow content”, which includes style.

What I don’t really get is: why don’t you have a <head> in your document, if you want to automatically generate HTML that is recommended by certain tools, and it’s allowed here, why don’t you have a head, or inject one if needed?

tani commented 1 month ago

https://html.spec.whatwg.org/multipage/dom.html#flow-content Oh, I see. thanks!

github-actions[bot] commented 1 month ago

Hi! This was closed. Team: If this was fixed, please add phase/solved. Otherwise, please add one of the no/* labels.

github-actions[bot] commented 1 month ago

Hi team! Could you describe why this has been marked as wontfix?

Thanks, — bb

remarkjs / remark-math