Could I get rid of the special meaning of backslash in markdown?

[ngocbh]

I am using markdown in latex to note faster and I also have the notes in two formats (latex -> pdf and markdown). But it is annoying when I have to use x\_i to write x_i in latex. I also have to remove all of those slashes when copying to latex format. Could I rerender the underscore _ in markdown where I want it to have no special meaning?

I see the option when we can rerender heading like this:
\markdownSetup{
renderers = {
headingOne = {\section{#1}},
headingTwo = {\subsection{#1}},
. },
}

But I don't know how to do in my case, Could you help me?

[Witiko]

You can set the underscores option to false:

\markdownSetup{underscores = false}

[ngocbh]

Amazing!! Thank you

[ngocbh]

@Witiko Can I do the same thing with backslash \. It seems to be unnecessary in my case. I mean maybe I do not need to escape anything in markdown special character. I usually use the backslash in math equations instead. I search in your document but have not found the that option.

[Witiko]

Sorry, there is currently no such option. However, in most cases, you should be able to use a single backslash. Can you show an example where you need several backslashes to achieve what you need?

[ngocbh]

Most cases I need to escape the backslash is when I need to use the backslash to escape other characters in latex formula. For example, I have to use \\\\ to create a new line rather than \\, \\[\\] instead of \[\] or \\{ instead of \{. It led me to fix the formula when I switched to latex. If you have the option to get rid of the special meaning of backslash in markdown, it will help me a lot when writing in hybrid mode.

[Witiko]

Such option is not yet implemented in the Lua parser. I will leave this issue open if anyone has the time and inclination to implement it.

[ngocbh]

another example:
hybrid mode in markdown

\\[distance[i] = 
    \begin{dcases}
        a & b \\\\\\
        c & d
    \end{dcases}
\\]

in latex:

\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]

I don't know why but I have to use six backslashes instead of four to make it work.

I have another question:
I am writing in .md file and embed to latex by using \markdownInput{ option. Could I have something like \stopmarkdown or \starttex option in markdown to begin latex mode in .md file.
For example:

\starttex
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
\stoptex

[Witiko]

I have another question:

I am writing in .md file and embed to latex by using \markdownInput{ option. Could I have something like \stopmarkdown or \starttex option in markdown to begin latex mode in .md file.

For example:

\starttex
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
\stoptex

Not at the moment, but you can go the other way around. For example, imagine having two files, main.tex and my-document.tex:

main.tex

\input my-document

my-document.tex

\begin{markdown}
some markdown text
\end{markdown}
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
\begin{markdown}
some other markdown text
\end{markdown}

[rconnorlawson]

Another example of this is when using the '#' character, which always has to be escaped in LaTeX. I use the LaTeX markdown environment with option hybrid=true.

What works now:

\begin{markdown}
    RRT$^\\#$ is a motion planner.
\end{markdown}

What I would prefer:

\begin{markdown}
    RRT$^\#$ is a motion planner.
\end{markdown}

In this case, the option to turn off escaping of backslashes only within TeX math mode would be sufficient.

Excellent package, by the way!

[Witiko]

@rconnorlawson The # character is special, since it starts headings. Therefore, markdown allows you to escape it as follows:

# A heading
\# Not a heading

However, markdown is not smart enough to only allow escaping in places where a heading may meaningfully start:

This backslash: \# will *also* not get printed.
Try at <https://spec.commonmark.org/dingus/>.

This is a more general issue and impacts most implementations of Markdown.

[nicofranzp]

Any idea if this is happening soon? I'm also having trouble with math environments and line breaks (\\\\).

[nicofranzp]

\starttex
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
\stoptex

I try to keep the sections of my documents in markdown so I can build static sites with them and use MD text editors. To compile the math and have automatic tags in equations I use MathJax. The only way it works is to enclose the math environment in $$ ... $$ or \[ ... \] (this is editable in MathJax).

When I finish the document I compile a PDF using LaTeX and the markdown package. Before that, I have to change the line breaks in all the equations and delete the double dollar signs so I don't get an error. In that moment the *.md used to generate the site diverges from the one used to generate the pdf, and editing becomes a problem.

I guess what I would like to have is way to use \[...\] (or similar compatible with MathJax) as a LaTeX delimiter that reads the double backslash as a line break. I don't have a clue on how to get there 😬

[Witiko]

I am not tackling this at the moment, since it would require that we try to parse LaTeX and separate text from math, which can never be done precisely, since LaTeX is Turing-complete. If we were to implement this, we would at least need a heuristic (e.g. anything between $ $, $$ $$, \[ \], and \begin{equation} \end{equation} is math, all else is text) that is well-defined and reasonably compatible with whatever black magic other markdown parsers are using.

[yfzhao20]

Nice package I think! Recently I have made some attempts about hybrid setting and other. Here are the results:

• _ mark

\documentclass{ctexart}
\usepackage{markdown}

\begin{document}
\begin{markdown}

undefined_object

\end{markdown}
\end{document}

It works! ✅

But after I enable "hybrid" option...

\documentclass{ctexart}
\usepackage{markdown}
\markdownSetup{hybrid = true}

\begin{document}
\begin{markdown}

undefined_object

\end{markdown}
\end{document}

ummmm🤔......It gives a bunch of errors:

Obviously it treats _ as subscript note in math environment. And at the same time underscores option fails.

I think it should be treated as markdown character but not math note if not in math environment, even hybrid enabled. Maybe it shold distinguish math environment ($$ $$, $ $, \[ \]. \( \)) firstly......

• So does ^ note

• But when using math environment, I have to replace \\ with \\\\... That is too much trouble to easily copy my markdown files into LaTeX documents...

• So I think the most important task is find the appropriate occasion to... to treat the "code" as LaTeX when hybrid option is open. Most of that are math environments. Maybe a lot of users don't write markdown directly in LaTeX editor but copy from other .md files.

By the way, fantastic and awesome package I think! Thank you nice developer🎉.

[Witiko]

I think it should be treated as markdown character but not math note if not in math environment, even hybrid enabled. Maybe it shold distinguish math environment ($$ $$, $ $, \[ \]. \( \)) firstly......

@yfzhao20 Thank you for your thoughts. Here is why I am not in favor of making the hybrid option any smarter than it is now:

• The Markdown package makes it extremely easy to switch between markdown and TeX.
• Using TeX commands eliminates several useful properties of markdown documents:
  • Markdown documents can be reused for multitarget publishing.
  • Markdown documents can't crash TeX, which makes it easier to locate the source of an error.
  • Markdown documents don't allow a malicious actor to execute code from the user's shell.
• Detecting whether a piece of a TeX document will be typeset in math mode is generally impossible, because:
  • TeX as a language is recognizable, but not decidable. By Rice's theorem, its semantic properties are also undecidable.
  • TeX code can in practice be analysed using simulation with timeouts (see e.g. LaTeXML), but doing so would require knowledge about the TeX engine and the TeX format used. Otherwise, we won't be able to understand commands such as \begin{equation} ... \end{equation}, which is specific to the TeX format of LaTeX. This runs contrary to the design of the Markdown package, which aims to be engine- and format-agnostic.
  • TeX code can be a part of a macro definition. A macro can be used both inside and outside math mode. It's unclear how we should treat such indeterminate TeX code.

Instead of making hybrid smarter, I would like to gradually make it less useful by introducing syntax extensions that address the common uses of TeX in markdown documents:

• TeX comments are useful for commenting and word wrapping, so we introduced the texComments option in version 2.10.0.
• The \label and \ref LaTeX commands are indispensable for cross-refencing in academic texts, so we plan to Make HTML attributes actionable #91, so that such functionality is available directly from within markdown.

Similarly, we could introduce a math Lua option, which would recognize common math environments ($$ $$, $ $, \[ \], \( \)) and make it possible to use ^, _, and \\ in them. This option would be independent on hybrid and it would not claim to detect whether math mode is used in TeX (which is generally impossible as discussed above). Such an option should strive for compatibility with whatever heuristics other markdown parsers (e.g. Pandoc) use to parse math, see also #61 (comment).

[Witiko]

I have to replace \\ with \\\\... That is too much trouble to easily copy my markdown files into LaTeX documents...

@yfzhao20 Consider the following markdown text: \[some link][1]. Here, \ will prevent [some link][1] from being interpreted as a link and will produce the following output: "[some link][1]". To prevent this interpretation, we can escape the backslash: \\[some link][1]. Now, we will receive the following typeset output: "\some link". Typesetting links preceded by backslashes is arguably not too useful, but it is a necessary precondition for being able to encode an arbitrary sequence of abstract elements from a markup language in its syntax.

In LaTeX, you can specify the size of the gap after a line break as follows: \\[2em]. Should Markdown be smart, detect that [2em] is not a link, and produce "\\[2em]" or should Markdown be predictable and produce "\[2em]"? Most markdown parsers seem to go with the latter approach, which is that \\ resolves to "\" regardless of the following text. Counterexamples are welcome.

[yfzhao20]

I think it should be treated as markdown character but not math note if not in math environment, even hybrid enabled. Maybe it shold distinguish math environment ($$ $$, $ $, \[ \]. \( \)) firstly......

@yfzhao20 Thank you for your thoughts. Here is why I am not in favor of making the hybrid option any smarter than it is now

Options with specific functions (LaTeX comment, math environment and so on) are indeed what I want! That's great🎉

In LaTeX, you can specify the amount of vertical skip after a line break as follows: \[2em]. Should Markdown be smart, detect that [2em] is not a link, and produce "\[2em]" or should Markdown be predictable and produce "[2em]"? Most markdown parsers seem to go with the latter approach, which is that \ resolves to "" regardless of the right context. Counterexamples are welcome.

By the way, what I means about \\ to \\\\ is also about math environment (but not common markdown text). It seems that the problem will be solved with math option 😀

Cheers!

[yfzhao20]

Can the issue be solved soon?🤝 I think this is the main reason that blocks me turning to LaTeX from markdown.. Unfortunately I'm not so good at Lua and maybe can not make some contributions to this project...

[Witiko]

@yfzhao20 I am sorry to say that there have always been tasks of higher priority for me to work on. 🙁

Recently, the upstream lunamark library has received support for raw attributes (see jgm#36), which I plan to port to the Markdown package in October (see #173). Perhaps you could use raw attributes for typing mathematical formulae:

Here is a mathematical formula:
``` {=tex}
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
```

Alternatively, you can contribute code or sponsor this issue. 🙂

[yfzhao20]

@Witiko Thanks for your effort !!! 🌹 I will try this feature later, and keep updating debug report. 😃

[Witiko]

In Markdown 2.18.0 (to be released on Monday), the raw_attribute option will be added that can be used to write math:

\documentclass{article}
\usepackage[fenced_code, raw_attribute]{markdown}
\usepackage{mathtools}
\begin{document}
\begin{markdown}
Here is a `\TeX`{=tex} formula:
``` {=tex}
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
```
\end{markdown}
\end{document}

[Witiko]

In Markdown 2.21.0 (released in February 2023), the tex_math_dollars option has been added that can be used to write inline and display math surrounded by dollar signs:

\documentclass{article}
\usepackage[tex_math_dollars]{markdown}
\usepackage{mathtools}
\begin{document}
\begin{markdown}
Here is a $\text{\TeX}$ formula:
$$distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
$$
\end{markdown}
\end{document}

[Witiko]

In Markdown 2.22.0 (to be released in March 2023), the tex_math_single_backslash and tex_math_double_backslash options have been added that can be used to write inline and display math surrounded by backslash-escaped parens and brackets, respectively:

\documentclass{article}
\usepackage[tex_math_single_backslash]{markdown}
\usepackage{mathtools}
\begin{document}
\begin{markdown}
Here is a \(\text{\TeX}\) formula:
\[distance[i] = 
    \begin{dcases}
        a & b \\
        c & d
    \end{dcases}
\]
\end{markdown}
\end{document}

[Witiko]

The issue seems solved with multiple approaches to writing math described in #61 (comment), #61 (comment), and #61 (comment). Therefore, I am closing the issue.