• Usage
  • Syntax
  • Templates and Filter
• Caveats
  • CSS Counter
  • Pandoc-Citeproc
• Credit

Define amsthm environment in YAML front matter and use it with a native pandoc div in the main document. Using the templates and filter provided, HTML and LaTeX output using amsthm can be realized.

Demo are available at https://ickc.github.io/pandoc-amsthm/.

pandoc-amsthm defines a new syntax above pandoc markdown. It is then processed through the use of provided pandoc templates and filter.

So far, only LaTeX and HTML related output are supported.

For example, as in template/include/default.yml,

---
amsthm:
  plain:
  - Theorem
  plain-unnumbered:
  - Lemma
  - Proposition
  - Corollary
  definition:
  - Definition
  - Conjecture
  - Example
  - Postulate
  - Problem
  remark:
  - Case
  remark-unnumbered:
  - Remark
  - Note
  proof:
  - proof
  parentcounter:
  - chapter
...

Notes:

• proof: & - [proof] is mandatory [1]

• parentcounter is optional, common choices are chapter, section. Depending on the document class, it can be part, chapter, section, subsection, subsubsection, paragraph, subparagraph. It only affects LaTeX output.

• plain, definition, and remark are the theorem styles provided by amsthm.

• the suffix -unnumbered means unnumbered, otherwise numbered. (i.e. you can also use definition-unnumbered)

• First letter of the amsthm environment should be capitalized (they will be printed as is in HTML), except for proof, which has to be in lower case (to match the pre-defined amsthm proof environment).

• The above YAML is equivalent to

  ---
  amsthm:
    plain:    [Theorem]
    plain-unnumbered: [Lemma, Proposition, Corollary]
    definition:   [Definition,Conjecture,Example,Postulate,Problem]
    definition-unnumbered:    []
    remark:   [Case]
    remark-unnumbered:    [Remark,Note]
    proof:    [proof]
    parentcounter:    [chapter]
  ...
  

[1] because amsthm predefines it.

Each amsthm environment should be defined with a native pandoc div, with a class named as the environment defined through the YAML front matter. Like this:

<div class="proof">
A Proof.
</div>

The provided templates and filter are needed for pandoc to process the above defined syntax properly.

To use the given filter in bin/, add --filter=<pathto>pandoc-amsthm.py to your pandoc command. If you put put it in your PATH, then you only need --filter=pandoc-amsthm.py. [2]

[2] Strictly speaking, you only need to include the filter for LaTeX output. HTML related outputs only requires the templates.

There are 2 ways to use the templates. If you do not need to customize the templates, 3 complete templates are provided in template/ folder. Use the template according to the output format by adding this in your pandoc argument: --template=<pathto>pandoc-amsthm.<ext>.

If you need to customize your template (or need other HTML related output not provided here, e.g. ePub.), 2 templates named are given in template/include/pandoc-amsthm.*. They are fragments only. You need to insert the given fragment into the head or preamble for HTML and LaTeX respectively.

In issue #3, there is a request on using the default without repeating the YAML front matter every time. It can be done. Using the files in template/include/default.*:

pandoc -H <PATHTO>default.html <INPUT>.md -o <OUTPUT>.html
cat <PATHTO>default.yml <INPUT>.md | pandoc -H <PATHTO>default.latex --filter=<PATHTO>pandoc-amsthm.py -o <OUTPUT>.pdf

template/include/makefile shows how the defaults are produced.

In the CSS defined through the HTML templates,

• a .dump is used, basically because I have 4 for loops together and I have no way to guarantee it doesn’t end with a comma, since any of the array can be empty.
• The CSS counter is reset by html. If you use other CSS, and have other CSS counter set by html, you need to change that (body is another possible choice). If there’s two separately defined CSS counter reset based on the same html or body then there would be trouble (and to resolve the conflict, they should be combined together).

Currently if pandoc-citeproc is used before this filter, there’s an error. So this filter should be used first. Like this: --filter=pandoc-amsthm.py --filter=pandoc-citeproc.

The Python script used is modified from chdemko/pandoc-latex-environment, which is under CeCILL-B license.