Publish markdown-it plugin (and vscode preview extension)

[universemaster]

Will you be publishing a Temml markdown-it plugin? https://www.npmjs.com/search?q=keywords:markdown-it-plugin

I currently use the katex plugin that vscode natively uses - https://github.com/mjbvz/markdown-it-katex .

But, when chrome properly supports mathml, I suspect I'll move to Temml.

On a similar note, do you have any interest in publishing a vscode preview extension? https://code.visualstudio.com/api/extension-guides/markdown-extension#adding-support-for-new-syntax-with-markdownit-plugins

[ronkok]

Will you be publishing a Temml […] plugin?

Probably not, and certainly not anytime soon. I already have enough on my plate without taking on more packages to maintain.

If any such plugin would require modification to Temml itself, I would stand by to help. Those plugins would be extremely valuable.

[universemaster]

Unfortunately, I feel the same way: that the plugins would be valuable, but am reluctant to take on the workload.

Maybe if someone from the community reads this, they may want to take it on?

[traeblain]

@universemaster Attempted a markdown-it plugin, and appears to work. I have a need for it that I'm exploring so hopefully should be able to keep it updated although based on the KaTeX plugin, it really doesn't need to be touched much. It works for my usage, hopefully it works for yours:

https://github.com/traeblain/markdown-it-temml

[runarberg]

I just returned to markdown-it-math after 7 years of unmaintenance.

It is highly customizable and supports a custom renderer, and I was hoping to document using Temml for LaTeX users. It currently defaults to mathup (an AsciiMath dialect), and that is not gonna change, but I want users to be able use Temml just as easily.

I haven’t tested it but it should be something like:

npm install --save markdown-it markdown-it-math@latest

import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";
import temml from "temml";

const md = markdownIt().use(markdownItMath, {
  inlineRenderer: (src) => temml.renderToString(src),
  blockRenderer: (src) => temml.renderToString(src, { displayStyle: true }),
});

You’d than need to make sure to import the stylesheet and font, etc. like usual.

Mathup supports the <math-up> custom element and currently I‘m debating whether to render the mathml string during markdown rendering (current behavior), or to instruct users to import the custom element and simply wrap the source inside a <math-up> element. Something similar could be done for Temml, or I could even sniff the custom element registry for <la-tex>, <math-up>, etc. See #79

[ronkok]

It's great to see progress happening with Markdown documents.

The choice of MathML vs. <la-tex> is entirely your call. My personal preference would be to take the server-side conversion all the way from Markdown to MathML and remove the client-side JavaScript entirely.

However, I also see a slight argument for a conversion to a <la-tex> element, with client-side rendering of that element. Temml has several workarounds for browser rendering issues. Most of them employ a CSS rule so they will not break rendered documents. That is, in most cases, web pages will just update the Temml CSS file after the browser fixes their problem. The MathML will not need to be re-generated.

The \raise function is the exception. It employs some inline padding that will need to be removed if and when browsers reach a sensible rendering of the <mpadded> element. \raise is infrequently used, so most documents will be fine, but the documents that do use it will remain unbroken if markdown-it emits a <la-tex> element and not MathML.

[runarberg]

I agree that it is probably better to instruct users to render to MathML on the server. The user experience is gonna be better if the page is loaded with the expression fully rendered. Thinking about this further I may actually save custom-element support for version 6 (or at least the sniffing part of it). Users should be able to opt in with a simple:

{
  inlineRenderer: (src, _token, md) => `<la-tex>${md.utils.escapeHtml(src)}</la-tex>`,
  blockRenderer: (src, _token, md) => `<la-tex display="block">${md.utils.escapeHtml(src)}</la-tex>`,
}

And I could even offer a convenience option:

{
  inlineCustomElement: "la-tex",
  blockCustomElement: ["la-tex", { display: "block" }]
}

I‘m actually working on a couple of more markdown-it plugins which employ the commonmark heuristics for backticks, except for dollar signs (I know markdown way more than LaTeX so I prefer a markdown behavior when including math). I think I will try custom-element sniffing there and see how it goes (I don‘t think they will be popular for LaTeX users).

As for mathup, it is fairly fast and lightweight so it won‘t matter much for user whether the rendering is on the server or the client. But I get the sense that way more user want to write in LaTeX than an ascii-math dialect, so I think I will document according to that.

[ronkok]

Regarding math delimiters, GitHub now recognizes $`…`$, in addition to $…$ and $$…$$. That enables authors to write LaTeX with a $ in it and seems to me like a pretty good addition.

[runarberg]

I was following the discussion on this commonmark thread. I think I might have to change the option to openDelimiters and closeDelimeters which accepts an array of pairs [open, close], which defaults to something like:

{
  inlineDelimiters: [["$", "$"], ["$`", "`$"]],
  blockDelimiters: [["$$", "$$"]],
}

Me, personally, I prefer to use the heuristics defined in the commonmark spec, so no stuff like $$ block math $$ on the same line as the delimiters. But that is not what users coming from the LaTeX world are expecting and I don’t think I can expect them to adopt my preference here.

I might also end up making Temml a second default for markdown-it-math, and add it as an optional peer dependency. The way I do the default renderer is I import mathup dynamically in a try ... catch block and if it fails I default the renderer to a span or a div element. I think it might be a good landing to have Temml the second try in that chain.

The problem I see with that is that if users are using it in a global environment (e.g. as vs-code plugin) all their expressions might fail if they globally install mathup. So I might end up adding yet another option preferredDefaultRenderer = "mathup" | "temml" to make up for that, so that at least users could fix it without removing a globally installed package.

[runarberg]

I just published markdown-it-math v5.0.0-rc.1 and will probably publish v5.0.0 next week. I opted not to have temml as a second default (it felt overly complex and brittle) but I documented how to use temml with it. I did some thorough testing as well (including different fonts and macros) and included a playground which uses temml here:

https://runarberg.github.io/markdown-it-math/demo/?latex

The gist of it is:

npm install --save markdown-it markdown-it-math temml

import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";
import temml from "temml";

// Optional, if you want macros to persist across equations.
const macros = {};

const md = markdownIt().use(markdownItMath, {
  inlineRenderer: (src) => temml.renderToString(src, { macros }),
  blockRenderer: (src) =>
    temml.renderToString(src, { displayStyle: true, macros }),
});

[ronkok]

I like it. It's great to see Temml and Markdown become more integrated.