Clarify backslash escape patterns

[alnoki]

Describe the bug

HTML elements

| Price | Size | Side                                    |
| ----- | ---- | --------------------------------------- |
| 1004  | 10   | <span style={{color: 'red'}}>Ask</span> |

gets reformatted to

| Price | Size | Side                                     |
| ----- | ---- | ---------------------------------------- |
| 1004  | 10   | \<span style={{color: 'red'}}>Ask</span> |

Here, the inserted backslash gets entered into the table

LaTeX

$1.44 \log_2 n$

gets reformatted to

$1.44 \\log_2 n$

Here, the double backslash breaks the LaTeX. This also happens for double $ delimiters:

$$\LARGE t_i = l_d t_d 10 ^ {d_q}$$

gets reformatted to

$$\\LARGE t_i = l_d t_d 10 ^ {d_q}$$

Reproduce the bug

Source file at https://github.com/econia-labs/econia/blob/main/doc/doc-site/docs/overview/orders.md Render at https://econia.dev/overview/orders

List your environment

[tool.poetry.dev-dependencies]
autoflake = "^2.0.1"
mdformat = "0.7.16"
mdformat-frontmatter = "2.0.1"
mdformat-gfm = "0.3.5"
mdformat_footnote = "0.1.1"

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[nschloe]

I guess that'll be hard one to fix. GitHub decided to divert from standard Markdown syntax in their math implementation, and I'm not sure if one can expect that the entire toolchain follows suit. In any case, it'll be hard. (If you're interested, check out my blog posts about it, 1 and 2.)

The best solution for this would be for GitHub to use the backtick math notation like GitLab, i.e.,

$`...`$

[alnoki]

I guess that'll be hard one to fix. GitHub decided to divert from standard Markdown syntax in their math implementation, and I'm not sure if one can expect that the entire toolchain follows suit. In any case, it'll be hard. (If you're interested, check out my blog posts about it, 1 and 2.)

The best solution for this would be for GitHub to use the backtick math notation like GitLab, i.e.,

$`...`$

Thanks for the references. I'll note that this is actually for Docusaurus, not GitHub.

Also, what about the backslash in the html elements?

[nschloe]

Also, what about the backslash in the html elements?

That one looks like a bug to me that's reasonable to fix.

[hukkin]

HTML elements

Your HTML does not seem to be valid so the escape character is there by design.

Perhaps you meant

| Price | Size | Side                               |
| ----- | ---- | ---------------------------------- |
| 1004  | 10   | <span style="color:red">Ask</span> |

LaTeX

Neither CommonMark nor GFM have any support for LaTeX or any math equation syntax. mdformat-myst brings support for a specific dollarmath syntax, but it seems you don't have it installed. For non standard Markdown syntax support (such as LaTeX) you might want to create your own mdformat plugin.

[alnoki]

HTML elements

Your HTML does not seem to be valid so the escape character is there by design.

Perhaps you meant

| Price | Size | Side                               |
| ----- | ---- | ---------------------------------- |
| 1004  | 10   | <span style="color:red">Ask</span> |

LaTeX

Neither CommonMark nor GFM have any support for LaTeX or any math equation syntax. mdformat-myst brings support for a specific dollarmath syntax, but it seems you don't have it installed. For non standard Markdown syntax support (such as LaTeX) you might want to create your own mdformat plugin.

@hukkin Thanks for the tips here! Since I'm using Docusaurus the HTML format you suggested doesn't work (Docusaurus instead requires JSX), so I ended up defining a custom ColoredText component in src/components/ColoredText.js:

import React from 'react';

export default function ColoredText({children, color}) {
  return (<span style={{color: color}}>{children}</span>);
}

Then I updating the table entries to read:

| Price | Size | Side                                           |
| ----- | ---- | ---------------------------------------------- |
| 1004  | 10   | <ColoredText color="#ff0000">Ask</ColoredText> |

This way the formatter doesn't end up inserting a backslash, and Docusaurus doesn't throw an error for inlining with non-JSX syntax.

As for the LaTeX, mdformat-myst ended up solving the problem! I just had to remove mdformat_footnote from pyproject.toml since both tools handle footnotes:

[tool.poetry.dev-dependencies]
autoflake = "^2.0.1"
mdformat = "0.7.16"
mdformat-frontmatter = "2.0.1"
mdformat-myst = "0.1.5"
mdformat-gfm = "0.3.5"