6

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.

Peter Prescott
  • 183
  • 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? – David Carlisle Dec 04 '20 at 00: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. – Peter Prescott Dec 04 '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. – David Carlisle Dec 04 '20 at 12:48

3 Answers3

10

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 different text" | pandoc --template mwe.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

Community
  • 1
DG'
  • 21,727
  • 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... – Peter Prescott Dec 03 '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 03 '20 at 15:32
  • 1
    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. – Peter Prescott Dec 03 '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... – Peter Prescott Dec 03 '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? – Peter Prescott Dec 03 '20 at 16:30
  • Well, this all seems to be confused. 1.) Your development and you production system should have the same versions. 2.) Transforming a latex document into a pandoc template is one thing, installing a latex class in your texmf another. 3.) Maybe you don't need to write a new template, maybe using sagej as documentclass in the default pandoc latex template does suffice – DG' Dec 03 '20 at 16:51
  • Well 1) is because I'm trying to do this with Docker containers, which adds another (minor?!) layer of complication, but means when it works it will be trivial to reproduce anywhere and everywhere. – Peter Prescott Dec 03 '20 at 16:54
  • With regards to 2) and 3), I don't know how/can't seem to be able to install a class in such a way that Pandoc recognizes it. Putting it in the same folder as the template does not work, nor does putting it in the pandoc -v user data directory (which is /.local/share/pandoc. Related questions have been asked here and here without answers... – Peter Prescott Dec 03 '20 at 17:56
  • Is latex part of the docker? – DG' Dec 03 '20 at 18:46
  • To be clear: pandoc has nothing to do with the class files. The only thing pandoc does, is trans form some input to latex and fill a template with the generated values. It then calls latex to make a pdf and latex must find the class file, not pandoc – DG' Dec 03 '20 at 18:54
  • Let us continue this discussion in chat. – Peter Prescott Dec 03 '20 at 19:11
3

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
Oleg Lobachev
  • 1,499
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/
Peter Prescott
  • 183