amsthm support

[kasperpeulen]

Is there any chance that pandoc will ever support amsthm package ?
So that I can convert my mathematical articles to html.

[mpickering]

What kind of support do you envisage?

[timtylin]

The precursor to this will be some sort of delimiter for formatted blocks of text. Unfortunately, this does not exist for now in any major flavors of Markdown aside from the use of HTML div blocks.

[timtylin]

(You can obviously insert begin/end theorem statements directly as latex commands do get theorem environments)

[kasperpeulen]

As html output I would suggest something lime this: http://drz.ac/2013/01/17/latex-theorem-like-environments-for-the-web/

I thought that pandoc doesn't support latex environments, so that would probably be something that is necessary to implement amsthm.

[kasperpeulen]

I also noted that there is written some very basic version of amsthm:
https://github.com/jgm/pandocfilters/blob/master/examples/theorem.py

[mpickering]

I'm still very confused about what precise feature you are suggesting. This is what I'm guessing -

• LaTeX Reader recognises a amsthm environments
• HTML Writer does something special with theorem environments

Is this correct?

[kasperpeulen]

@mpickering Yeah, that is correct.

I'm using the tool authorea. Which uses pandoc to convert the latex I write, to html. For example:
https://www.authorea.com/users/9325/articles/9455/_show_article

So, what I would like, is to have the amsthm environments be recognized by pandoc, and have pandoc converted it to html which looks as close as possible to the pdf output.

The amsthm package, doesn't has predefined theorem environments if I recall correctly, but you have to define them yourself, so I think it would be good if pandoc works the same.

\usepackage{amsthm}
\newtheorem{thm}{Theorem}  
\newtheorem{lem}{Lemma}

And then you can create a theorem or lemma like:

\begin{thm}Here is a theorem
\end{thm}
\begin{lem}Here is a lemma.
\end{lem}

Well, amsthm, gives those theorems a specific style, so I would like if the HTML writer would do similar styling to those blocks. Something like:

.theorem {
    display: block;
    margin: 12px 0;
    font-style: italic;
}
.theorem:before {
    content: "Theorem [theorem count].";
    font-weight: bold;
    font-style: normal;
}

[j2kun]

This is a sorely needed feature. Literally every math paper I have ever read uses amsthm, and I cannot convert any paper without it.

[ickc]

I'm interested in such feature as well.

A Working Demo of Using amsthm in pandoc markdown to HTML and LaTeX generations

I opened a repository in ickc/pandoc-amsthm: provide amsthm environments in pandoc with valid output in LaTeX and HTML.

It provides CSS, LaTeX file, and some pandoc filters to target HTML and LaTeX output, using native pandoc divs with amsthm environments defined through the class of the divs. Supports for 13 environments is provided. CSS is unfinished though. See https://ickc.github.io/pandoc-amsthm/index.pdf for demo.

For example, in the markdown, the following will define a theorem:

<div class="theorem">
...
</div>

It's only a proof of concept (and used personally). I am thinking about using YAML front matter together with pandoc native divs instead to create general amsthm environments. But there are some obstacles.

Generalizing it by defining the amsthm environments through YAML front matter?

For example, looking at my TeX file:

\usepackage{amsthm}

\theoremstyle{plain} % default
\newtheorem{theorem}{Theorem}[chapter]
\newtheorem{lemma}[theorem]{Lemma}
\newtheorem{proposition}[theorem]{Proposition}
\newtheorem*{corollary}{Corollary}

\theoremstyle{definition}
\newtheorem{definition}{Definition}[chapter]
\newtheorem{conjecture}{Conjecture}[chapter]
\newtheorem{example}{Example}[chapter]
\newtheorem{postulate}{Postulate}[chapter]
\newtheorem{problem}{Problem}[chapter]

\theoremstyle{remark}
\newtheorem*{remark}{Remark}
\newtheorem*{note}{Note}
\newtheorem{case}{Case}

% proof is predefined, see documentation

We could define YAML variables like:

amsthm: true
amsthmplain:    [theorem, lemma, propostion, corollary]
amsthmdef:  [definition,conjecture,example,postulate,problem]
amsthmremark:   [remark,note,case]

It is very easy to use a for loop in the templates to create a in line style sheet in HTML template, and create those definitions in LaTeX template.

But the problem is how to decide the optional argument to use through YAML front matter. (Nested array?)

Another problem is how to write a filter which use the information in the metadata to decide which divs are converted into amsthm environments. I'm inexperienced in writing pandoc filter so I'm not sure if it can be done. If the 3 arrays amsthmplain, amsthmdef and amsthmremark can be extracted in the filter, it should be quite easy to look for the divs with such classes.

Another possible way is to provide a general mapping from a divs to latex environment. For example,

<div class="theorem" latex="true">
...
</div>

Then a filter is wrote to look for any divs that has latex="true" and turn it into a \begin{theorem}...\end{theorem} pairs. (I wish such kind of universal switch can make into the official pandoc too.)

Summary

The current approach is totally manual, each environments are defined one by one, and in all 3 formats: .css, .tex, .py (although a script can automate it a bit further then I did already). Are there any interests to make this a general amsthm usage? An if there's such general way of working with amsthm, will @jgm be interested in making it into the official pandoc?

[ickc]

I made a filter in pandocfilters/latexdivs.py at master · ickc/pandocfilters that do what I described above:

Pandoc filter to convert divs with latex="true" to LaTeX
environments in LaTeX output. The first class
will be regarded as the name of the latex environment
e.g.
<div latex="true" class="theorem etc">...</div>
will becomes
\begin{theorem}...\end{theorem}

I wish this syntax can make into the official pandoc so that a filter is not needed.

Anyway, this filter can be used instead to target amsthm in LaTeX and HTML output.

The filters I mentioned previously will do something in the HTML output as well. But I think a better practice is to leave the native div as native div and use CSS and CSS counter to do the tricks. The CSS I used above did that, without the CSS counter yet.

[andrew222651]

@ickc That looks really useful. Is there support for environment numbering?

[ickc]

@amacfie

Yes, I just updated the css to have basic numbering by css counter. And in the .tex I defined, there are numbering.