8 Limitations

As outlined in Document compilation, papaja builds on pandoc to render Markdown into PDF and DOCX documents. Markdown provides good common basis for these and other document types but the common basis necessarily limits the degree of control that can be exerted over the rendered document. For example, there is currently no way to generate tables with pandoc in which cells span multiple rows or columns. Similarly, it is not possible to insert page breaks into a document. Both of these limitations have been raised with the developers of pandoc (see here and here), but it may take a while for them to be addressed.

8.1 PDF documents

pandoc builds on LaTeX to render PDF documents. As discussed in Markdown text formatting, when the R Markdown document contains LaTeX code it is kept as-is and can be used to exert greater control over the final result. For example, to create a page break in the rendered document you can use the LaTeX command \pagebreak. Similarly, tables with column spanners can be created by using the corresponding LaTeX code. Hence, the limited control offered by pandoc can be compensated by using LaTeX code and papaja resorts to this approach, for example, in apa_table().

8.1.1 Customizing the document preamble

You can exert further control over your PDF documents by customizing the LaTeX preamble. Consider the following example: By default, LaTeX arranges paragraphs and section headings so that they fill the page. This can sometimes lead to unwanted vertical spacing, Figure 8.1.

An example of large vertical spacing between paragraphs and section headings in a rendered PDF document kindly provided by John Sakaluk.

Figure 8.1: An example of large vertical spacing between paragraphs and section headings in a rendered PDF document kindly provided by John Sakaluk.

If you prefer white space at the bottom of the page, rather than between paragraphs, you can overwrite this default behavior by including \raggedbottom in the document preamble. To do so, add the following to the YAML front matter of your document:

  - \raggedbottom

8.2 Microsoft Word documents

In contrast, there is no simple way to compensate for the limited control offered by pandoc when rendering Microsoft Word documents. This is the reason why some of papaja’s features are only available if the to-be-rendered document is in PDF format, such as some Rendering options and some features of apa_table() (see Tables). More over, rendered documents in DOCX format require some manual work before they fully comply with APA guidelines. We, therefore, provide the following checklist of necessary changes:


  1. add a header line with running head and page number

If necessary,

  1. position author note at the bottom of page 1
  2. move figures and tables to the end of the manuscript
  3. add colon to level 3-headings
  4. in figure captions,
    • add a colon following the figure numbers and italicize
      (e.g. “Figure 1. This is a caption.”)
  5. in tables,
    • add horizontal rules above the first and below the last row
    • add midrules

We hope to automated some of these points in the future as the flexibility of pandoc increases.

Comments and Questions

Icons by Icons8