3.3 PDF document

To create a PDF document from R Markdown, you specify the pdf_document output format in the YAML metadata:

• Typora is one of the most popular Markdown editors, and for good reason.
• From markdown to PDF: pandoc MANUAL.txt-pdf-engine=xelatex -o example13.pdf; PDF with numbered sections and a custom LaTeX header.
• Chromium download starts automatically when Markdown PDF is installed and Markdown file is first opened with Visual Studio Code. However, it is time-consuming depending on the environment because of its large size ( 170Mb Mac282Mb Linux280Mb Win). During downloading, the message Installing Chromium is displayed in the status bar.

Mou for Mac → LightPaper (Mac) LightPaper is a simple editor for Mac users that offers a distraction-free writing interface. It offers several in-built fonts, and you can also export your content in HTML, PDF or audio files. LightPaper for Mac → Free Markdown Tools Markdown.css. Markdown.css makes HTML markup look like plain text Markdown.

Within R Markdown documents that generate PDF output, you can use raw LaTeX, and even define LaTeX macros. See Pandoc’s documentation on the raw_tex extension for details.

Note that PDF output (including Beamer slides) requires an installation of LaTeX (see Chapter 1).

3.3.1 Table of contents

You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option. For example:

If the TOC depth is not explicitly specified, it defaults to 2 (meaning that all level 1 and 2 headers will be included in the TOC), while it defaults to 3 in html_document.

You can add section numbering to headers using the number_sections option:

If you are familiar with LaTeX, number_sections: true means section{}, and number_sections: false means section*{} for sections in LaTeX (it also applies to other levels of “sections” such as chapter{}, and subsection{}).

3.3.2 Figure options

There are a number of options that affect the output of figures within PDF documents:

• fig_width and fig_height can be used to control the default figure width and height (6.5x4.5 is used by default).

• fig_crop controls whether the pdfcrop utility, if available in your system, is automatically applied to PDF figures (this is true by default).

  • If you are using TinyTeX as your LaTeX distribution, we recommend that you run tinytex::tlmgr_install('pdfcrop') to install the LaTeX package pdfcrop. You also have to make sure the system package ghostscript is available in your system for pdfcrop to work. For macOS users who have installed Homebrew, ghostscript can be installed via brew install ghostscript.

  • If your graphics device is postscript, we recommend that you disable this feature (see more info in the knitr issue #1365).

• fig_caption controls whether figures are rendered with captions (this is true by default).

• dev controls the graphics device used to render figures (defaults to pdf).

For example:

3.3.3 Data frame printing

You can enhance the default display of data frames via the df_print option. Valid values are presented in Table 3.3.

For example:

3.3.4 Syntax highlighting

The highlight option specifies the syntax highlighting style. Its usage in pdf_document is the same as html_document (Section 3.1.4). For example:

3.3.5 LaTeX options

Many aspects of the LaTeX template used to create PDF documents can be customized using top-level YAML metadata (note that these options do not appear underneath the output section, but rather appear at the top level along with title, author, and so on). For example:

A few available metadata variables are displayed in Table 3.4 (consult the Pandoc manual for the full list):

3.3.6 LaTeX packages for citations

By default, citations are processed through pandoc-citeproc, which works for all output formats. For PDF output, sometimes it is better to use LaTeX packages to process citations, such as natbib or biblatex. To use one of these packages, just set the option citation_package to be natbib or biblatex, e.g.

3.3.7 Advanced customization

3.3.7.1 LaTeX engine

By default, PDF documents are rendered using pdflatex. You can specify an alternate engine using the latex_engine option. Available engines are pdflatex, xelatex, and lualatex. For example:

The main reasons you may want to use xelatex or lualatex are: (1) They support Unicode better; (2) It is easier to make use of system fonts. See some posts on Stack Overflow for more detailed explanations, e.g., https://tex.stackexchange.com/q/3393/9128 and https://tex.stackexchange.com/q/36/9128.

3.3.7.2 Keeping intermediate TeX

R Markdown documents are converted to PDF by first converting to a TeX file and then calling the LaTeX engine to convert to PDF. By default, this TeX file is removed, however if you want to keep it (e.g., for an article submission), you can specify the keep_tex option. For example:

3.3.7.3 Includes

You can do more advanced customization of PDF output by including additional LaTeX directives and/or content or by replacing the core Pandoc template entirely. To include content in the document header or before/after the document body, you use the includes option as follows:

3.3.7.4 Custom templates

You can also replace the underlying Pandoc template using the template option:

Consult the documentation on Pandoc templates for additional details on templates. You can also study the default LaTeX template as an example.

3.3.8 Other features

Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section 3.1.10.4 for details. You can also pass more custom Pandoc arguments through the pandoc_args option (Section 3.1.10.5), and define shared options in _output.yml (Section 3.1.11).

This document is for people who are unfamiliar with command line tools. Command-line experts can go straight to the User’s Guide or the pandoc man page.

First, install pandoc, following the instructions for your platform.

Pandoc is a command-line tool. There is no graphic user interface. So, to use it, you’ll need to open a terminal window:

• On OS X, the Terminal application can be found in /Applications/Utilities. Open a Finder window and go to Applications, then Utilities. Then double click on Terminal. (Or, click the spotlight icon in the upper right hand corner of your screen and type Terminal – you should see Terminal under Applications.)

• On Windows, you can use either the classic command prompt or the more modern PowerShell terminal. If you use Windows in desktop mode, run the cmd or powershell command from the Start menu. If you use the Windows 8 start screen instead, simply type cmd or powershell, and then run either the “Command Prompt” or “Windows Powershell” application. If you are using cmd, type chcp 65001 before using pandoc, to set the encoding to UTF-8.

• On Linux, there are many possible configurations, depending on what desktop environment you’re using:

  • In Unity, use the search function on the Dash, and search for Terminal. Or, use the keyboard shortcut Ctrl-Alt-T.
  • In Gnome, go to Applications, then Accessories, and select Terminal, or use Ctrl-Alt-T.
  • In XFCE, go to Applications, then System, then Terminal, or use Super-T.
  • In KDE, go to KMenu, then System, then Terminal Program (Konsole).

You should now see a rectangle with a “prompt” (possibly just a symbol like %, but probably including more information, such as your username and directory), and a blinking cursor.

Let’s verify that pandoc is installed. Type

and hit enter. You should see a message telling you which version of pandoc is installed, and giving you some additional information.

First, let’s see where we are. Type

on Linux or OSX, or

on Windows, and hit enter. Your terminal should print your current working directory. (Guess what pwd stands for?) This should be your home directory.

Let’s navigate now to our Documents directory: type

and hit enter. Now type

(or echo %cd% on Windows) again. You should be in the Documents subdirectory of your home directory. To go back to your home directory, you could type

The .. means “one level up.”

Go back to your Documents directory if you’re not there already. Let’s try creating a subdirectory called pandoc-test:

Now change to the pandoc-test directory:

If the prompt doesn’t tell you what directory you’re in, you can confirm that you’re there by doing

(or echo %cd%) again.

OK, that’s all you need to know for now about using the terminal. But here’s a secret that will save you a lot of typing. You can always type the up-arrow key to go back through your history of commands. So if you want to use a command you typed earlier, you don’t need to type it again: just use up-arrow until it comes up. Try this. (You can use down-arrow as well, to go the other direction.) Once you have the command, you can also use the left and right arrows and the backspace/delete key to edit it.

Most terminals also support tab completion of directories and filenames. To try this, let’s first go back up to our Documents directory:

Now, type

and hit the tab key instead of enter. Your terminal should fill in the rest (test), and then you can hit enter.

To review:

• pwd (or echo %cd% on Windows) to see what the current working directory is.
• cd foo to change to the foo subdirectory of your working directory.
• cd .. to move up to the parent of the working directory.
• mkdir foo to create a subdirectory called foo in the working directory.
• up-arrow to go back through your command history.
• tab to complete directories and file names.

Type

and hit enter. You should see the cursor just sitting there, waiting for you to type something. Type this:

When you’re finished (the cursor should be at the beginning of the line), type Ctrl-D on OS X or Linux, or Ctrl-Z followed by Enter on Windows. You should now see your text converted to HTML!

What just happened? When pandoc is invoked without specifying any input files, it operates as a “filter,” taking input from the terminal and sending its output back to the terminal. You can use this feature to play around with pandoc.

By default, input is interpreted as pandoc markdown, and output is HTML. But we can change that. Let’s try converting from HTML to markdown:

Now type:

and hit Ctrl-D (or Ctrl-Z followed by Enter on Windows). You should see:

Now try converting something from markdown to LaTeX. What command do you think you should use?

You’ll probably want to use pandoc to convert a file, not to read text from the terminal. That’s easy, but first we need to create a text file in our pandoc-test subdirectory.

Important: To create a text file, you’ll need to use a text editor, not a word processor like Microsoft Word. On Windows, you can use Notepad (in Accessories). On OS X, you can use TextEdit (in Applications). On Linux, different platforms come with different text editors: Gnome has GEdit, and KDE has Kate.

Start up your text editor. Type the following:

Now save your file as test1.md in the directory Documents/pandoc-test.

Note: If you use plain text a lot, you’ll want a better editor than Notepad or TextEdit. You might want to look at Sublime Text or (if you’re willing to put in some time learning an unfamiliar interface) Vim or Emacs.

Go back to your terminal. We should still be in the Documents/pandoc-test directory. Verify that with pwd.

Now type

(or dir if you’re on Windows). This will list the files in the current directory. You should see the file you created, test1.md.

Mac Markdown To Pdf

To convert it to HTML, use this command:

The filename test1.md tells pandoc which file to convert. The -s option says to create a “standalone” file, with a header and footer, not just a fragment. And the -o test1.html says to put the output in the file test1.html. Note that we could have omitted -f markdown and -t html, since the default is to convert from markdown to HTML, but it doesn’t hurt to include them.

Check that the file was created by typing ls again. You should see test1.html. Now open this in a browser. On OS X, you can type

On Windows, type

You should see a browser window with your document.

To create a LaTeX document, you just need to change the command slightly:

Try opening test1.tex in your text editor.

Pandoc can often figure out the input and output formats from the filename extensions. So, you could have just used:

Pandoc knows you’re trying to create a LaTeX document, because of the .tex extension.

Now try creating a Word document (with extension docx).

Markdown Download Mac

If you want to create a PDF, you’ll need to have LaTeX installed. (See MacTeX on OS X, MiKTeX on Windows, or install the texlive package on Linux.) Then do

You now know the basics. Pandoc has a lot of options. At this point you can start to learn more about them by reading the User’s Guide.

Here’s an example. The --mathml option causes pandoc to convert TeX math into MathML. Type

then enter this text, followed by Ctrl-D (Ctrl-Z followed by Enter on Windows):

Now try the same thing without --mathml. See the difference in output?

If you forget an option, or forget which formats are supported, you can always do

Markdown Editor Mac Open Source

to get a list of all the supported options.

On OS X or Linux systems, you can also do

Pandoc Markdown To Pdf Mac

to get the pandoc manual page. All of this information is also in the User’s Guide.

Markdown Online

If you get stuck, you can always ask questions on the pandoc-discuss mailing list. But be sure to check the FAQs first, and search through the mailing list to see if your question has been answered before.