Simple reference for users who move from other markdown ecosystems

[mrwunderbar666]

I've been playing around with this excellent package, but noticed some behaviours that are unusual when moving from other markdown flavours. I normally use pandoc to convert my markdown files to pdf (via latex).

Therefore, I started making a simple reference document. If you find it useful, it could be added to the repository: https://gist.github.com/mrwunderbar666/9fde11201d9ec3b66e11486c6cf2fdc3

[Witiko]

Thank you for your helpful list. Do note that a lot of the behavior you describe as different from regular markdown is due to your use of the hybrid option, which allows you to mix TeX code with Markdown code but also keeps many special characters of TeX (such as &) special, which means that you need to escape them by hand if you just want to typeset them.

[mrwunderbar666]

Thanks for the comments, I updated the file.

But what is the "proper" way of writing inline math and more complicated expressions with the markdown package?

E.g.,

S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
        = \frac{1}{n}\sum_{i}^{n} X_i

$$ S_n = \frac{X_1 + X_2 + \cdots + X_n}{n} = \frac{1}{n}\sum_{i}^{n} X_i $$

[Witiko]

Writing math expressions without having to deal with indent and backslashes is a long-standing issue, see #61.

Here is what you can do now:

• You can escape from markdown by typing \end{markdown} and then typing your math expression. This does not help you if you store your markdown documents in separate files and use \markdownInput to include them.
• You can escape from markdown by enabling the contentBlocks option, saving your math expression in file math-expression.tex and then typing /math-expression.tex in your markdown document, see also the user manual. The semantics of content blocks are somewhat vague, but the default behavior is to input *.tex and *.md documents, among other things.

Here are the proposed solutions:

• Backport support for raw attributes from the upstream lunamark library, which would allow us to type raw TeX code (both inline and in blocks) without enabling the hybrid option and without having to deal with indent and backslashes, see also Could I get rid of the special meaning of backslash in markdown? #61 (comment). This one is slated to arrive next month unless some contributor implements it (then it might arrive sooner) or I get hit by bus (then it might arrive later).
• Add smartBackslashes and texMathDollars options that would make our markdown parser disregard indent between dollar signs and be more context-sensitive about escaping backlashes, see Could I get rid of the special meaning of backslash in markdown? #61 (comment) and also Section 3.1 of our article in TUGboat 43:1. This one has been postponed for a while and does not sit well with me; it is well-specified but also quite heavy-handed in that the smartBackslashes option breaks compatibility with CommonMark and is not straightforward to implement. One would hope for a more elegant solution.

[Witiko]

See #61 (comment), #61 (comment), and #61 (comment) for the up-to-date ways of writing inline and display math.