Skip to content

Instantly share code, notes, and snippets.

@michaelt
Created June 9, 2011 21:23
Show Gist options
  • Save michaelt/1017790 to your computer and use it in GitHub Desktop.
Save michaelt/1017790 to your computer and use it in GitHub Desktop.
Simple Pandoc default.latex with comments
%!TEX TS-program = xelatex
\documentclass[12pt]{scrartcl}
% The declaration of the document class:
% The second line here, i.e.
% \documentclass[12pt]{scrartcl}
% is a standard LaTeX document class declaration:
% we say what kind of document we are making in curly brackets,
% and specify any options in square brackets.
% (The previous line is a pseudo-comment, declaring that we will
% use the special XeTeX machinery for its more extensive font list
% and its use of unicode;
% in general, LaTeX 'comments' like this one
% begin with % and end with a linebreak.)
% Note that there we have nothing in the nature of a template;
% it's just a standard bit of LaTeX pandoc will copy unaltered into the
% LaTeX file it is writing. But suppose you wrote something
% more akin to the corresponding line in Pandoc's default
% latex.template file, say:
% \documentclass$if(fontsize)$[$fontsize$]$endif${scrartcl}
% then you would have invented a 'variable', fontsize,
% and could write things like
% `markdown2pdf my.txt --xetex --variable=fontsize:12pt -o my.pdf` or
% `pandoc -r markdown -w html my.txt -s --xetex --variable=fontsize:24pt -o my.tex`.
% If we specified --variable-fontsize:12, then template substitution
% would yield a LaTeX document beginning
% \documentclass[12pt]{scrarcl}
% which is just what we said anyway.
% But we could also specify a different fontsize.
% I don't use this `--variable=....`functionality myself;
% I have a couple of basic templates I call with
% `--template=whatever.template` which I can also
% easily inspect to adjust things like font size as I please.
% While we are discussing the declaration of the document class...
% here's an alternative command for two column landscape,
% not bad for some purposes. (If you strike the word 'landscape'
% you will have two narrow newspaperlike
% columns; scientists like that, because irrationality must
% show itself somewhere):
%\documentclass[12pt,twocolumn,landscape]{scrartcl}
% Columns are too close together in LaTeX so we add this
% `columnsep` command:
%\setlength{\columnsep}{.5in}
% I use the special 'komascript' article class "scrartcl"
% reasons I can't entirely remember; I'm not sure it's that great.
% One reason is the unimportant one that, like many classes,
% it allows very big fonts which are convenient for booklet printing
% in the idiotic American way by shrinking letterpaper pages.
% the standard minimal LaTeX 'article' class declaration would be something like:
% \documentclass[12pt]{article}
% or for big type:
% \documentclass[24pt]{extarticle}
% but these restrict you to old-fashioned LaTeX materials.
% Note that Kieran Healy uses the swank 'Memoir' class,
% \documentclass[11pt,article,oneside]{memoir}
% which might be worth a look.
% Enough about the document class.
% -- We are in swanky unicode, XeTeX land, and must now import these packages:
\usepackage{fontspec,xltxtra,xunicode}
% fontspec means we can specify pretty much any font.
% Because we are using XeTeX material,
% this template needs to be called with the `--xetex` flag.
% Symbols:
% Pandoc imports the extensive `amsmath` collection of symbols
% for typesetting ordinary math.
\usepackage{amsmath}
% if you use exotic symbols you need to import specific packages, eg. for
% electrical engineering diagrams, musical notation, exotic currency symbols,
% the unspeakable rites of freemasonry etc.
% `babel`:
% The `babel` package, among other things, lets you determine what
% language you are using in a given stretch of text, so that typesetting
% will go well. Here we specify that mostly, we are speaking English:
\usepackage[english]{babel}
% Margins, etc:
% the `geometry` package makes for convenient adjusting of margins, which is what
% you asked about. Of course it can do much more, even make coffee for you:
\usepackage{geometry}
\geometry{verbose,letterpaper,tmargin=3cm,bmargin=3cm,lmargin=3cm,rmargin=3cm}
% so if you just keep a copy of this template in the directory you are working in, you
% can adjust the margins by going into this file and messing with the margins.
% the syntax is very unforgiving, but permits 3cm and 2.5in and some other things.
% Font:
% Here I set my main font, which is an Apple Corporation Exclusive, golly.
% \setmainfont{Hoefler Text}
% \setromanfont[Mapping=tex-text,Contextuals={NoWordInitial,NoWordFinal,NoLineInitial,NoLineFinal},Ligatures={NoCommon}]{Hoefler Text}
% Hoefler Text is okay, but note the long discussion of 'contextuals' which is necessary to cools off
% some of its show-offy properties. (You can make your essay look like the
% Declaration of Independence by specifying e.g. Ligatures={Rare} )
% If you have a copy you might try it; as it is
% I will comment it out and supply something more certain to be around:
\setmainfont{Times Roman}
% Properly one should specify a sanserif font and a monospace font
% see e.g. the example of Kieran Healy:
% \setromanfont[Mapping=tex-text,Numbers=OldStyle]{Minion Pro}
% \setsansfont[Mapping=tex-text]{Minion Pro}
% \setmonofont[Mapping=tex-text,Scale=0.8]{Pragmata}
% But I hate sanserif fonts, and anyway there are defaults.
% Heading styles:
% These commands keep the koma system from making stupid sans serif section headings
\setkomafont{title}{\rmfamily\mdseries\upshape\normalsize}
\setkomafont{sectioning}{\rmfamily\mdseries\upshape\normalsize}
\setkomafont{descriptionlabel}{\rmfamily\mdseries\upshape\normalsize}
% I'm puzzled why I have this foonote speciality,
% I wonder if it's part of my problem I've been having, but wont look
% into it now.
\usepackage[flushmargin]{footmisc}
% \usepackage[hang,flushmargin]{footmisc}
% So much for my personal template.
% Everything that follows is copied from the pandoc default template:
% I will interpolate a few comments, the comments that are in
% the default template will be marked % --
% Paragraph format:
% Pandoc prefers unindented paragraphs in the European style:
\setlength{\parindent}{0pt}
% ... with paragraph breaks marked by a slight lengthening of
% the space between paragraphs:
\setlength{\parskip}{6pt plus 2pt minus 1pt}
% Page format:
\pagestyle{plain}
% The default `plain` pagestyle just numbers the pages,
% whereas
% \pagestyle{empty}
% would give you no numbering.
% After one-million man-years of macro-composition,
% there are also fancy pagestyles with much wilder options
% for headers and footers, of course.
% Footnotes
% if you have code in your footnotes, the million macro march
% kind of bumps into itself.
% Pandoc, having just rendered your text into LaTeX,
% knows whether the 'variable' `verbatim-in-note` is True, and
% If it is, it asks for a LaTeX package that solves the dilemma:
$if(verbatim-in-note)$
\usepackage{fancyvrb}
$endif$
% Lists formatting:
% note sure what 'fancy enums' are; something to do with lists,
% as the further comment suggests:
$if(fancy-enums)$
% -- Redefine labelwidth for lists; otherwise, the enumerate package will cause
% -- markers to extend beyond the left margin.
\makeatletter\AtBeginDocument{%
\renewcommand{\@listi}
{\setlength{\labelwidth}{4em}}
}\makeatother
\usepackage{enumerate}
$endif$
% Table formatting:
% What if you make a table? -- Pandoc knows, of course, and
% then declares that its variable `table` is True and
% imports a table package suitable to its pleasantly simple tables.
% Needless to say infinitely complicated tables are possible in
% LaTeX with suitable packages. We are spared the temptation:
$if(tables)$
\usepackage{array}
% Continuing on the topic of tables ... (we havent reached `endif`).
% The commented out line below is in the default pandoc latex.template.
% Some unpleasantness with table formatting must be corrected.
% -- This is needed because raggedright in table elements redefines \\:
\newcommand{\PreserveBackslash}[1]{\let\temp=\\#1\let\\=\temp}
\let\PBS=\PreserveBackslash
$endif$
% Subscripts:
% Pandoc remembers whether you used subscripts, assigning True to
% its `subscript` variable
% It then needs to adopt a default with an incantation like this:
$if(subscript)$
\newcommand{\textsubscr}[1]{\ensuremath{_{\scriptsize\textrm{#1}}}}
$endif$
% Web-style links:
% markdown inclines us to use links, since our texts can be made into html.
% Why not have clickable blue links even in
% learned, scientific, religious, juridical, poetical and other suchlike texts?
% Never mind that they have been proven to destroy the nervous system!
% First, what about the fact that links like http://example.com are
% technically code and thus must not be broken across lines?
% [breaklinks=true] to the rescue!
% Nowadays LaTeX can handle all of this with another half million macros:
\usepackage[breaklinks=true]{hyperref}
\hypersetup{colorlinks,%
citecolor=blue,%
filecolor=blue,%
linkcolor=blue,%
urlcolor=blue}
$if(url)$
\usepackage{url}
$endif$
% Images.
% In ye olde LaTeX one could only import a limited range of image
% types, e.g. the forgotten .eps files. Or else one simply drew the image with suitable
% commands and drawing packages. Today we want to import .jpg files we make with
% our smart phones or whatever:
$if(graphics)$
\usepackage{graphicx}
% -- We will generate all images so they have a width \maxwidth. This means
% -- that they will get their normal width if they fit onto the page, but
% -- are scaled down if they would overflow the margins.
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth
\else\Gin@nat@width\fi}
\makeatother
\let\Oldincludegraphics\includegraphics
\renewcommand{\includegraphics}[1]{\Oldincludegraphics[width=\maxwidth]{#1}}
$endif$
% Section numbering.
% Here again is a variable you can specify on the commandline
% `markdown2pdf my.txt --number-sections --xetex --template=/wherever/this/is -o my.pdf`
$if(numbersections)$
$else$
\setcounter{secnumdepth}{0}
$endif$
% Footnotes:
% Wait, didn't we already discuss the crisis of code in footnotes?
% Evidently the order of unfolding of macros required that
% we import a package to deal with them earlier
% and issue a command it defines now. (Or maybe that's not the reason;
% very often the order does matter as the insane system of macro expansion
% must take place by stages.)
$if(verbatim-in-note)$
\VerbatimFootnotes % -- allows verbatim text in footnotes
$endif$
% Other stuff you specify on the command line:
% You can include stuff for the header from a file specified on the command line;
% I've never done this, but that stuff will go here:
$for(header-includes)$
$header-includes$
$endfor$
% Title, authors, date.
% If you specified title authors and date at the start of
% your pandoc-markdown file, pandoc knows the 'values' of the
% variables: title authors date and fills them in.
$if(title)$
\title{$title$}
$endif$
\author{$for(author)$$author$$sep$\\$endfor$}
$if(date)$
\date{$date$}
$endif$
% At last:
% The document itself!:
% After filling in all these blanks above, or erasing them
% where they are not needed, Pandoc has finished writing the
% famous LaTeX *preamble* for your document.
% Now comes the all-important command \begin{document}
% which as you can see, will be paired with an \end{document} at the end.
% Pandoc knows whether you have a title, and has already
% specified what it is; if so, it demands that the title be rendered.
% Pandoc knows whether you want a table of contents, you
% specify this on the command line.
% Then, after fiddling with alignments, there comes the real
% business: pandoc slaps its rendering of your text in the place of
% the variable `body`
% It then concludes the document it has been writing.
\begin{document}
$if(title)$
\maketitle
$endif$
$if(toc)$
\tableofcontents
$endif$
$if(alignment)$
\begin{$alignment$}
$endif$
$body$
%$if(alignment)$
\end{$alignment$}
$endif$
\end{document}
@pgbrandolin
Copy link

pgbrandolin commented Aug 11, 2017

Excellent stuff!
This annotated and customized template is what I really needed to quickly climb the "learning curve".

THANKS!

@joaopcnogueira
Copy link

Thank you for the file as well as the comments explanation.

I listened about markdown today and I thought it is fantastic to use it alongside with pandoc to convert .md files to .pdf or .html.

One thing I could not understand yet is how to change to right file in order to change the \documentclass, for example. You file here shed some light on it, but still some doubts remains... Where can I find the default.latex file used as standard by pandoc?

@EmTee70
Copy link

EmTee70 commented Jun 21, 2018

First of all - Thank You!
@joaopcnogueira I had the same question, found:
https://tex.stackexchange.com/questions/296990/latex-and-pandoc-templates
pandoc -D latex > ~/.pandoc/default.latex && $EDITOR ~/.pandoc/default.latex
But it is in the Docs: https://pandoc.org/MANUAL.html#templates :-)

@regisd
Copy link

regisd commented Oct 12, 2018

Thanks a star! Can you please add a license to this work (ideally Apache 2)

@craigbass76
Copy link

Any idea why I'm getting ! LaTeX Error: Missing \begin{document} when I try to run pandoc -s --template="craig.latex" markdown_template.md -o markdown_template2.pdf ? I've saved this text (the latex template) into craig.latex.

@jeffmcneill
Copy link

Any idea why I'm getting ! LaTeX Error: Missing \begin{document} when I try to run pandoc -s --template="craig.latex" markdown_template.md -o markdown_template2.pdf ? I've saved this text (the latex template) into craig.latex.

Note: can do --template craig.latex just as well. Just make sure this is saved in the ~/.pandoc/templates directory.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment