Clarify backslash escape patterns about mdformat HOT 6 CLOSED

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

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! 🎉

from mdformat.

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

$`...`$

from mdformat.

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?

from mdformat.

Also, what about the backslash in the html elements?

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

from mdformat.

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.

from mdformat.

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"

from mdformat.