2

I want to use Pandoc to convert markdown text files to beautifully formatted PDFs using LaTeX templates. I want to be able to do this reproducibly across unknown future machines, so I am using the official Pandoc Docker image to do it through a Docker container, as recommended here. I have successfully got it working with the Eisvogel Pandoc Latex template...

-- but I am perplexed by how to use a standard LaTeX template, such as those freely available at http://www.latextemplates.com/ (specifically let's say this one) or offered by academic journals (such as this one), given my particular configuration with Markdown, Pandoc, and Docker (which can be reproduced precisely from its git repository).

Specifically I think I have two questions:

  1. The 'standard templates' mentioned above don't exactly seem to me to be templates -- they include their example text with their LaTeX markup. How do I extract whatever necessary to map this on to the Markdown + Pandoc LaTeX template paradigm?

  2. They use multiple .tex files and/or accompanying .cls files. How do I get these into the right place for a containerized Pandoc process to find?

This question addresses a similar issue, but is specifically interested in using RStudio.

3
  • If you want to use specific classes eg journal supplied one, why not write directly in latex, what is converting the example document into a pandoc template and then getting pandoc to convert markdown to latex to use the class you want gaining you? Dec 4 '20 at 0:03
  • Well I think it's fair to say that Markdown is quicker to learn and easier to read than LaTeX -- the tradeoff is that it is less powerful and precise. But using Pandoc means that it is often possible to use the power of TeX while keeping the simplicity of Markdown. I have found this true with managing citations, for example. Dec 4 '20 at 12:35
  • 1
    sure I use markdown as well, but using markdown and "going with the flow" to get whatever your markdown processor produces is easier than using latex. But taking an explicit publisher supplied class and defining rules to map markdown syntax to all the class-supplied non standard commands is likely to be much harder than simply using the latex class. If you are the publisher and are setting up a pandoc based pipeline that's going to be used 1000s of times then yes. But for an author for one or two submissions, I doubt it is useful. Dec 4 '20 at 12:48
6

1.

A pandoc latex template is just a regular latex file with some placeholder variables in it. You can print the default template with pandoc -D latex > default.latex.

This means, that you can use any existing latex file and just add those variables to make a template.

Let's take this minimal latex document mwe.tex:

\documentclass{article}
\begin{document}
Here is some text.
\end{document}

Now you can replace Here is some text with $body$ and execute echo "Here is some text" | pandoc --template mew.tex -s --to latex and you will see, that$body$ is replaced with the text.

That way, you can make a pandoc template out of any latex file. Just replace the texts and commands in the latex file with pandoc variables. Of course you need to load all the packages that are used by pandoc! You can consult the default template to see, what pandoc usually requires.

How the templating engine works in detail and which variables are available is documented in the manual: https://pandoc.org/MANUAL.html#templates

2.

Where to store the files? Pandoc finds files in the current directory and in the data-directory. pandoc -v will print the data-dir on your system. If your data-dir is $HOME/.local/share/pandoc, then the templates will be found under: $HOME/.local/share/pandoc/templates

11
  • 1
    With your suggested minimal template, I get Error producing PDF. ! Undefined control sequence. l.3 \hypertarget. If I print the default template and try and then use that explicitly, I get Error producing PDF. ! LaTeX Error: Environment CSLReferences undefined. I'm not sure where to start addressing these errors... Dec 3 '20 at 14:20
  • Sure, if you use more advanced features than simple text, you need to load more packages. Read the default template and the manual, if you want to understand, what's going on.
    – DG'
    Dec 3 '20 at 15:32
  • Okay, so I've got the minimal template working. I needed to usepackage{hyperref} and then copy the $if(graphics)$... and $if(csl-refs)$... sections from the default. Dec 3 '20 at 16:25
  • And my problem with the default was that I was trying to run the default from my system's pandoc, which is a different version from the docker container, and for some reason the CSLReferences was changed to/from (?) cslreferences... Dec 3 '20 at 16:27
  • But the question for making use of standard templates remains. Eg. the Sage academic template says in its README, 'Simply place sagej.cls and sagedoc.tex in your system's usual directories and typeset using your LaTeX2e/PDFLaTeX command' -- but with Pandoc it looks like it's going to take considerably more work to do anything with it... Basically it sounds like you're saying I need to rewrite it completely with pandoc variables, as if it were an example rather than a template. Is that right? Dec 3 '20 at 16:30
2

With regards to (2), the question of where to put .cls files in order for the Docker-ized Pandoc process to find them, DG has helped me (in our continued discussion in chat) to understand that they need to be found by TeX, not by Pandoc.

And for TeX to be able to find them, they need to be in some subfolder of /texmf/ (in this particular Docker container -- to find the relevant place on whatever system, kpsewhich -var-value TEXMFHOME).

So if I have some .cls files in a folder called cls when I'm building the Docker image, then having this line in the Dockerfile does the trick:

COPY ./cls/* \
    /texmf/tex/latex/cls/
1

An alternative approach is to let pandoc do its job, and a (LaTeX) template do its. Let the template be main.tex. You put \include{contents.tex} instead of the body, i.e. between the \begin{document} and \end{document}.

Then you go on and generate contents.tex using pandoc. As you are playing with Docker, I expect it should be easy for you to automatize all this. Here is my take, using make:

main.pdf : main.tex contents.tex
    latexmk -pdf main

contents.tex : document.md
      pandoc -f markdown+smart+raw_tex -t latex $< -o $@

clean :
    rm -f contents.*
    latexmk -pdf -C main

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.