Description Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. Pandoc can convert between numerous markup and word processing formats, including, but not limited to, various flavors of Markdown, HTML, LaTeX and Word docx. Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. By data scientists, for data scientists ANACONDA. Pandoc GitHub Topics GitHub GitHub is where people build software. More than 56 million people use GitHub to discover, fork, and contribute to over 100 million projects.
Over the past few years, I have been using some dedicated note-taking softwareto manage my notes. But all these tools I have tried are unsatisfactory: theyare either slow or cumbersome when I want to search my notes. Finally, Idecided to take my notes in Markdown and convert them to PDF using Pandoc forreading. In this post, I will summarize how I do it.
本文的中文版本参见 这里。
Pandoc is a free and open-source document converter, widely used as a writing tool (especially by scholars) and as a basis for publishing workflows. It was created by John MacFarlane, a philosophy professor at the University of California, Berkeley.
Taking our notes in Markdown has several advantages:
- We can edit the Markdown files with our favorite editor, for example,Sublime Text, which means more efficient editing and pleasant writingexperience.
- Since a Markdown file is a textual file, we can search it using powerful
- search tool such as
grep
orripgrep
. - We can covert the Markdown files to various formats such as PDF, HTML, epub,mobi etc., for better reading experience, with the help of Pandoc.
- The notes are all text files and are small in size, which meanseasier and faster syncing or backup between your native PC and the cloudservice you use.
In this post, I would like to share how to generate beautiful PDF files fromMarkdown and give solutions to the issues I have encountered during theprocess.
Before we begin, you need to make sure that you have installed the followingtools:
- First, Pandoc.After installation, you should add the path of the Pandoc executable tothe system
PATH
variable. - TeX distribution. Please make sure that TeX has been installed on yoursystem. You can use either TeX Live orMiKTeX or MacTeX base on yourplatform. You may need to set up the
PATH
variable1. - A powerful text editor. One of my favorite is SublimeText. You can also choose to use VSCode or evenNeovim.
Background
For those who are not familiar with Pandoc, Pandoc is a powerful tool forconverting document between different formats. It is called the swiss knife ofdocument converter. There are actually two steps involved in convertingMarkdown files to PDF:
- Markdown files are converted to LaTeX source files.
- Pandoc invokes the
pdflatex
,xelatex
or other TeX command and converts.tex
source file to the final PDF file.
Because I often use non-ASCII characters in my files and my Markdown files usequotation, table and other complex format, I have met a few problems during theconversion process. In the following text, I will introduce how to solve theseissues.
How to Handle Languages other than English
By default, Pandoc uses
pdflatex
command to generate PDF files, which can nothandle Unicode characters well. You will encounter errors when you try toconvert Markdown files containing Unicode characters to PDF files.In order to handle Unicode characters, we need to use
xelatex
commandinstead. For the CJK languages, you need to use CJKmainfont
option to givethe proper font which supports the language you are using2. In this post, I willuse the Chinese language as an example.On Windows systems, for Pandoc version above 2.0, you can use the followingcommand to generate the PDF file:
In the above command,
KaiTi
is the name of a font which supports the Chinesecharacters. How do we find a font supporting a particular language? First,you need to know the language codefor the language you are using. For example, the language code for Chinese iszh
. Then, use the fc-list
command to look up the fonts which support thislanguage3:The output of command is like the following:
The font name is the string after the font location. Since the font names maycontain spaces, you need to quote the font name when you want to use aparticular font, e.g.,
-V CJKmainfont='Source Han Serif CN'
.In Pandoc version 2.0,
--pdf-engine
option replaces the old --latex-engine
option. OnLinux systems where the Pandoc version may be old, the above command will notwork. You need to use the following command instead4:On Linux systems, the way to find the font supporting your language is the sameas Windows system.
Block quote, table and list are not correctly rendered
The reason is that Pandoc requires that you leave an empty line before blockquote, list and table environment. If the lines in the block quote are notcorrectly broken, i.e., all the lines are merged as one paragraph, you can adda space after each line to solve this issue.
Add highlight to block code
Pandoc supports block code syntax highlighting for many languages and offersseveral highlight themes. To list the highlight themes that Pandoc provides,use the following command:
To list all the languages that Pandoc supports, use the following command:
To use syntax highlighting for different languages, you need to specify thelanguage in the block quote and use
--highlight-style
, e.g.,:In the above command, we use the
zenburn
theme, I also recommend using thetango
or breezedark
theme.Use numbered section and add TOC
By default, there is no table of contents (TOC) in the generated PDF and nonumbers in the headers5. To add TOC, use the
--toc
option; to add sectionnumbers, use the -N
option. A complete example is as follows:Add colors to links
According to the Pandoc user guide, we can add colors to different links viathe
colorlinks
option to separate the links from the normal texts:colorlinksadd color to link text; automatically enabled if any of linkcolor,filecolor, citecolor, urlcolor, or toccolor are set
To customize the color of different types of links, Pandoc offers differentoptions:
linkcolor, filecolor, citecolor, urlcolor, toccolorcolor for internal links, external links, citation links, linked URLs,and links in table of contents, respectively: uses options allowed by xcolor,including the dvipsnames, svgnames, and x11names lists
For example, to set the URL color to
NavyBlue
and set the TOC color to Red
,we can use the following command:Note that the
urlcolor
option will not color the raw URL links in the text.To color those raw links, you can enclose those links with <>
, e.g.,<www.google.com>
.Change the PDF margin
The default margin for the generated PDF is too large. According to the PandocFAQ,you can use the following option to change the margin:
The complete command is:
Error when using backslash inside Markdown
In ordinary Markdown format, it is fine to use backslash characters inside thefiles. But Pandoc interpret the backslash and string after it as LaTeX commandby default. As a result, you may encounter weirederrors when trying to compileMarkdown files containing backslash characters. Based on discussionshere andhere, the solution is to makePandoc treat the Markdown file as normal Markdown files and not interpret theLaTeX command. You need to use the following flag:
Or you can use two backslash to represent a literal backslash, e.g.,
sometxt
. If you want to express a LaTeX command, enclose the command withinline code block, like this: textt{}
.Add background color to inline code
In translating Markdown source file to TeX files, Pandoc use the
texttt
command to represent the inline code. So inline code has no background color inthe generated PDF files. To increase the readability of inline code, we canmodify the texttt
command to add background color to text.First, we need to create a file named
head.tex
and add the following settingsto it:When converting Markdown files, use the
-H
option to refer the head.tex
file, e.g.,:In the generated PDF, the inline code will have grey background color. You canchange the background color as you wish.
Change the default style of block quote
By default, when converting Markdown to PDF, Pandoc use the
quote
environment forMarkdown block quotes. The texts inside quotation are only indented, making ithard to recognize the environment.We can create a custom environment to add background color and indentation tothe quotation environment. Add the following setting to
head.tex
:When you want to convert Markdown file to PDF, you can use the followingcommand:
The produced PDF is like the following:
References
- Change background color of quotation.
- Redefining existing environment in LaTeX.
Put the settings to head.tex
You may have noticed the clumsiness if you try to customize a lot of settings.When converting Markdown to PDF, we often need to use several settings. If youspecify all these options on the command line, it would be time consuming andcumbersome to edit. A good way is ease the issue is to put some commandsettings to
head.tex
file and refer to this file during Markdown file conversion.For example, we can put the settings related to margin, inline codehighlighting, and link color to
head.tex
:Click to see the code.
Nested list level exceed the limit
One reader Karl Liu mentioned thatif the nested list level exceeds 6, you will encounter the following error whentrying to generate PDF file:
! LaTeX Error: Too deeply nested.
More detailed discussions can be foundhere. The solution proposed is toadd the following settings in
head.tex
:Click to see the code.
Add the
-H head.tex
option when compiling PDF files.Add anchors in Markdown
I try to use anchors in Markdown following the discussionhere.Unfortunately, in the generated PDF, the anchor does not work: when I click thelinking text, there is no jump to the destination page.
Instead, we should use the attribute to give an id to the location we want tojump to and then refer to it in other places using the id. Here is an example:
How to resize image
We can also resize images using the attribute. You can specify width or heightin absolute pixel values or as percentage relative to the page or column width.For example:
How to start a new page for each section
By default, when you generate PDF from Markdown files, each section started bythe level 1 header do not start from the new page: it will continue from wherethe last section ends. If you want to start a new page when a new sectionstarts, you need to add the following settings to
head.tex
according tothis:But when I tried to produce PDF with the updated
head.tex
files, I got anerror:According to discussionshere,it is because Pandoc’s default LaTeX redefines the
pragraph
command and wehave to disable this behaviour. We need to use -V subparagraph
when invokingthe pandoc
command:Start a new page only after TOC
What if we only want to add a new page after the table of contents page? Aneasy way is to hack the
tableofcontents
command. Add the following commandto head.tex
to redefine tableofcontents
command:In the above command, we first save the old command and then redefine it toavoid recursive calls.
Line breaks
In Markdown, you can create a hard linebreak by appending two spaces after a line:
Using space at the line end for formating is annoying since it cause thetrailing whitespace warning. The space characters are also not visible.
Pandoc also provides an
escaped_line_breaks
extension. You can use
in the end of a line followed by newline characterto represent a hard line break:Images references
Pandoc supports LaTeX command inside Markdown, to refer to an image, you can use the LaTeX syntax:
It is cumbersome to switch to the terminal and use Pandoc to generate the PDFfiles and preview it after finishing writing the Markdown files. To simply theprocess, I use the Sublime Text build system for building PDF file andpreviewing. I use the light-weight Sumatra PDFreader for PDFpreviewing.
An example build system is shown below:
Click to see the code.
You can download the build system and
head.tex
filehere.Pandoc is not recognized on Windows systems
For some reasons unknown to me, when using the above build systems to compileMarkdown files, I encountered the following errors:
‘pandoc’ is not recognized as an internal or external command, operableprogram or batch file.
After looking up the Sublime Text documentation, I find that we can add
path
in the build system. So I adjust the above build system:Click to see the code.
After that, everything goes well.
In this post, I give a complete summary on how to generate beautiful PDF filesfrom Markdown. I also share several solutions to the issues I have encountered.I hope that you can now generate beautiful PDF from Markdown files.
- Anchors in Pandoc
- Pandoc hard line break
- Make sure that you can use
latex
command on the command line. ↩︎ - For other languages, you need to use
--mainfont
option. ↩︎ - For Windows system, you can use
fc-list
command after installing the TeX Live full edition. For Linux systems, this command is usually pre-installed. ↩︎ - Tested on Pandoc version 1.12.3.1. ↩︎
- Only the font size varies for different header levels. ↩︎
Table of Contents
- General Introduction
- The Writing Workflow in Scrivener
- More Writing Tips
TL;DR (simple summary)
This guide is a series of steps, which you can combine a-la-carte to integrate Scrivener (an app that excels at organised writing), and Pandoc (a tool that excels at transforming text to documents). Scrivener already comes with MultiMarkDown, but in my opinion Pandoc provides numerous additional benefits and installation is quite simple. In addition, Pandocomatic flexibly manages Pandoc settings directly within Scrivener.
- Install the latest
pandoc
andpandocomatic
. - Configure one or more
pandocomatic
“recipes”; you can base them on mine shared below. - In Scrivener, use a front-matter document containing the required settings and compile via the MultiMarkdown format (this option generates Pandoc-specific output too). Here is a complete compile format to demonstrate the necessary settings.
- Scrivener’s compile post-processing triggers
pandocomatic
, automagically creating the final output(s) for you.
As a sample of the fuller workflow, I’ve made a self-contained Scrivener project (you still need to install
pandoc
and pandocomatic
first). This should give you a better idea of the various parts of the workflow, and you can look at the simultaneously produced PDF/HTML/DOCX/TXT outputs from the sample project to get an idea of the sort of end documents that are possible.Scrivener has many options, and to better understand the workflow outlined on this page you should read at least sections §21 and §24 of the Scrivener user manual!
Introduction
Scrivener (macOS / Windows) is a program for all types of writers, handling the structural organisation and constructive process of writing like nothing else. You write and manage text, ideas, figures and reference materials all in one place without having to worry about the final “look”. The final “look” is handled by a process called compiling, where you choose the output format and select the contents with great flexibility. Though Scrivener uses rich text internally, it has excellent integration with plain text markdown. Compiling your Scrivener projects via markdown offers numerous advantages over rich text: it creates more structured, beautiful and flexible documents without lots of fussing in a Word processor or layout software. For example:
- Binder headings are automatically converted into semantic heading levels (properly nested Headings 1-6).
- Figures and figure captions get proper styling.
- Semantically styled block quotes, code blocks (with full syntax highlighting), and many inline styles.
- Mathematical equations are properly parsed to many output formats.
- You can generate multiple outputs (PDF, LaTeX, DOCX, PPTX, ODT, EPub3, HTML etc.) simultaneously from a single compile; and trigger further tools to automate many workflows.
- You can use a Microsoft Word/LibreOffice source file to provide all page setup (paper size / modified headers & footers etc.) and fully customised styles without any fussing in a word processor afterwards.
- For academics, Pandoc enables generation of a full Bibliography using thousands of available publication styles.
- For technical writers, you can add semantic custom block and span structures (warning or info boxes for example).
- For LaTeX users, there is a lot of flexibility using rich templates and meta-data.
This all save you lots of time, especially if you compile regularly during collaborative editing.
Because of Pandoc’s great flexibility, there are many possible settings to configure. To simplify this, you can run Pandoc using “template” tools like Pandocomatic. For each document output, the template specifies all the options in Scrivener front-matter and/or a seperate configuration file. Pandocomatic templates allow you to run pre– and post–processors for more complex workflows (i.e. you could automate moving a HTML file to a web server after Scrivener compile). To use the Pandocomatic templates with Scrivener, you specify their name in the front–matter or metadata, and all the settings are automated when Pandoc is run.
UPDATE:: In Pandoc V2.8+, you can create “sets” of Pandoc options: see some examples here. I still prefer
pandocomatic
(described below) as I can use metadata, processor scripts and gain more control, but I think this defaults system will be great for others who want a simpler setup. The workflow I use is just one of many ways of using Pandoc and Scrivener together…Requirements
Apart from Scrivener (V3.x minimum required for this workflow), you should install Pandoc and Pandocomatic. This requires a small amount of typing into the macOS terminal. You can install
pandoc
directly, but IMO it is better to use Homebrew to install pandoc
, as it can help keep everything up to date (pandoc
receives regular automatic updates via homebrew). So first, follow the instructions to install Homebrew (info for the security conscious):And then install
pandoc
using the brew
command in the terminal:If you already installed
pandoc
manually, but want to use brew
from now on, then you can use brew link --overwrite ..
instead of brew install ..
.macOS Mojave and earlier users: the latest versions of Pandocomatic are not compatible with the ancient version of Ruby in macOS Mojave and earlier (macOS Catalina is OK), and so you need to install a newer version of Ruby first. Read Installing Ruby for more details!
You use Ruby’s
gem
command to install pandocomatic
(if you are using macOS Catalina’s built-in Ruby, you must put sudo
at the start of the commands, if you used brew
or rbenv
to install Ruby, no sudo
is required):To keep both Pandoc and Pandocomatic up-to-date, you can run the update commands like so every week or so:
Configuration
The most important folder for this workflow is the Pandoc data directory: since Pandoc V2.7 it is
$HOME/.local/share/pandoc
($HOME
is your user directory, for example /Users/johndoe/
; previous to V2.7 the folder was found at $HOME/.pandoc
). Though not required, it is recommended to organise all your templates, filters and other files within this folder (pandocomatic uses the Pandoc data directory by default). To create your $HOME/.local/share/pandoc
folder:All folders starting with a
.
are a hidden by default, but you can open them in Finder in two ways: 1) using the shortcut ⌘ + SHIFT + G and typing the path, in this case ~/.local/share/pandoc
; or 2) using the Terminal and typing:You can explore my working Pandoc folder here. It is comprised of a series of subfolders of files Pandoc and pandocomatic use during converison. You can install my Pandoc folder by downloading it and unzipping its contents into your
$HOME/.local/share/pandoc
, or if you know how to use git
you can just clone (or fork) it from Github.pandocomatic
uses a configuration file usually stored at the root of the Pandoc data directory: $HOME/.local/share/pandoc/pandocomatic.yaml
. A simplified sample pandocomatic.yaml
is viewable here; this won’t work without customisation, but it gives you an idea of how pandocomatic-templates work (full documentation here). The basic idea is you create several pandocomatic-templates, and each pandocomatic-templates collects together a bunch of settings and configurations to produce a particular output. So I have docx
pandocomatic-templates which is a basic Word conversion, but also a docx-refs
which runs the bibliographic tools to generates a bibliography automatically for a docx file output.For the rest of the files in the Pandoc data directory: all custom Pandoc templates reside in
$HOME/.local/share/pandoc/templates
, and Pandoc filters in $HOME/.local/share/pandoc/filters
. For bibliographies, I symbolically link my Bibliography.bib into in $HOME/.local/share/pandoc
and store my Journal style files in $HOME/.local/share/pandoc/csl
. pandocomatic
enables the use of pre– and post–processor scripts and these are stored in their own subfolders.Writing in Scrivener
With Scrivener 3’s new styles system (§15.5 user manual), there is a huge change to how you can write with markdown. You can use named paragraph styles (like “blockquote”), and named inline styles (like “emphasis” or “superscript”) as you would writing in rich text (i.e. there is no need to add markdown syntax in the editor!) With the compile system (§23—user manual), Scrivener will add a prefix/suffix to create the required plain-text markdown. So for example, create an inline style called
Strong
, and in compile set the prefix to ** and suffix to ** and Scrivener automates conversion from the RTF style to markdown! You can even rebind ⌘I and ⌘B to trigger the Emphasis and Strong styles directly. I use Scrivener styles to visualise structure andgenerate the Pandoc markup itself:Figure 1 — The cursor shows that both inline Strong and paragraph Caption styles are both active. Note whitespace is visualised and styles are used to give visual structure to the Scrivener writing environment. These will all be transformed into the correct markdown on compile…
There are two parts of this Styles setup: first you must create the editor’s named paragraph & inline Styles, which you do using the Styles Panel (CTRL+s) or Format ⇨ Style menu . If you want to import some Styles from my sample project to get you started, open the Styles Panel ⇨ ⚙ Gear Icon menu ⇨ Import Styles… and select my Workflow.scriv project file. For the Compile Style rules, you can make these yourself in the Compile format editor, or more easily you can download my customised compile preset here. Install it (Compiler ⇨ Gear Icon ⚙ ⇨ Import Formats…) to get a flavour of how one can convert styles to markdown, and it now has the
scrivomatic
script built-in (needs Scrivener V3.03+).Figure 2 — The Scrivener 3 Compile Format
Scrivomatic.scrformat
in the editor, showing how the inline style “Strong Emphasis” is converted into the correct markdown using prefix & suffix text. IMPORTANT TIP: for block/paragraph styles you will need to enter newlines directly into the prefix/suffix edit fields; you do this usingoptionreturn.Enable Show invisible characters
Because markdown is sensitive to whitespace (double return to delineate paragraphs, 4 spaces/1 tab to delineate code blocks etc.), you should aim to use whitespace consistently: for new paragraphs and between any blocks of content spacespacereturnreturn is optimal. Showing invisible characters in the Scrivener editor makes potential formatting issues when compiling simple to fix. Enable it using
View ▶︎ Text Editing ▶︎ Show Invisibles
, and change their colour in Preferences ▶︎ Appearance ▶︎ Textual Marks ▶︎ Invisible Characters
. If you do not wish to use returnreturn to delineate paragraphs in the Scrivener editor, you can use Scrivener’s compile replacements, or Compile format Editor ▶︎ Transformations ▶︎ Convert to plain text ▶︎ Paragraph spacing
(§24.13 user manual).Use the Binder for all document structure
Try not to not use markdown # headings within text documents themselves but create documents at the correct level hierarchy in the Binder. Scrivener is great at compiling the levels of the Binder structure into the correct heading levels for you, and you benefit from being able to use the outlining and organisation tools within Scrivener.
Images
Scrivener can transform images that are embedded with a line of text (§21.4.1 user manual) into markup that generates proper semantic
<figure>
and <figcaption>
elements. I now prefer to link images (Fig. 21.2—user manual) from the binder rather than by using the standard Pandoc markup: ![Figure caption](linked_image){.my_style}
; in both cases (embedded or linked-from-binder) Scrivener will correctly export the image file into the compile folder. Scrivener 3 has a nice new feature where you can binder-link figures (Insert ▸ Image Linked to Document
), they are not embedded but still visible in the document, to add a caption to these you can use a caption style or [] brackets around the caption (described at the end of §21.4.1—user manual).Footnotes
Scrivener will automatically convert footnotes into Markdown format for you. But there is one caveat in that you are not allowed to use Scrivener’s styles inside footnotes, and so if you want to use emphasis, strong or other character styles, you will have to use the Pandoc markup directly.
Cached
Scrivener Comments
Use comments and annotations freely. Scrivener 3 now allows you to transform comments to complex markup (§24.19.7—user manual) where the comment text
<$cmt>
AND the comment selection <$lnk>
are both correctly exported). This can be set in compile ▶︎ annotations…
— I use: <span><$lnk></span>
. For export to DOCX, you can use <span author='<$author>' date='<$date>'><$cmt></span><$lnk><span></span>
, which will transform into proper Word margin comments.Cross-referencing
Out of habit, I prefer to use Scrivener links when cross-referencing documents / exporting figures, and Scrivener’s placeholder tags to cross-reference figures and equations within the text. But for new users, Pandoc does have several cross-referencing filters (pandoc-crossref and pandoc-fignos for example) and you can also use these. The advantage of these systems is that they are more portable if you move your project out of Scrivener, the disadvantage being you will need to use markup directly. I have a quick crossref.scriv project available to show an example of using the
pandoc-crossref
filter.Compiling your Project:
In Scrivener, I ensure to remove all compile–metadata specified in the compile user interface (see screenshot here) so it doesn’t interfere with the custom metadata front-matter. I create a document called something like Pandoc metadata containing the YAML configuration block right at the top (read more detailed documentation here). You can use Scrivener placeholder tags in this document, to insert the title or other data from Scrivener’s extensive list (
Help ▸ List of All Placeholders…
).IMPORTANT: Scrivener’s autocorrect will “smarten” quotation marks and dashes and can capitalise keys like
title
or pandocomatic
, which will make Pandocomatic and Pandoc error, so please check keys like title
, author
& pandocomatic
are lowercase, straighten quotes and ensure the 3 hyphens are not converted into an em dash — also indentation in the metadata block must be spaces and not tabs.In the example YAML below, three templates are specified, so
pandocomatic
will run Pandoc three times to generate a DOCX, HTML and plain TXT file from the same single Scrivener compile:Pandoc Converter
The front matter should be the first document in the compile list and compiled as–is.
Figure 3 — I created a
Project ▸ Project Settings… ▸ Section Type
called “Frontmatter”, assigned this Section Type to ‘Pandoc metadata’, set ‘Pandoc metadata’ as Front Matter in the Compiler options, and then assigned it the AS-IS Section Layout.The Pandocomatic configuration template (
pandocomatic.yaml
) could contain something like the example below for the DOCX template specified above (generating a bibliography using the APA style (with linked citations) and a table of contents):In Scrivener, you select Multimarkdown as the compile document output and select a compile format that configures a post-processing tool to run pandocomatic automatically.
Scrivomatic post-processing script
You can run
pandocomatic
directly from Scrivener’s post-processing panel, but you may need to ensure the Environment
path is set up so Scrivener can find all the files and the other tools properly. Scrivomatic
is a small wrapper script (yes, welcome to the rabbit hole ?!) that handles this for you…It adds the paths for tools installed via
homebrew
, MacTeX
and Cabal
; and if you’ve used rbenv
, rvm
or conda
to install pandocomatic/panzer, it adds these paths too. It can also generate a detailed log file of the conversion (so you can check for missing references or other problems etc.). The easiest way to install it is to copy the raw code from here: scrivomatic
, then you want to install it by pasting it into the Post-processing Edit Script
edit field (leave Shell blank). You then configure the Arguments
field (adding different flags to control scrivomatic
, e.g. -l
opens scrivomatic.log in Console automatically):Figure 4 — Scrivener’s processing panel in the compile preset.
You can also download the script to your Downloads folder, move it to a directory on your path, and make sure it can be executed like so:
You can then run
scrivomatic
from terminal with the following command line options:Alfred Workflow
I also include an Alfred workflow so you can run
scrivomatic
directly from markdown files selected by Alfred:Firefox cleaner. Figure 5 — Alfred Workflow.
Writing tips for this Workflow
Pandoc - Pandoc User’s Guide
How-to use Custom Styles in Word and HTML
There are two recent features added to Pandoc, Fenced Divs and Custom Styles (see also bracketed spans), that when combined, enable any arbitrary custom Scrivener paragraph or character styles to be converted into Word styles or CSS classes. So for example, we can create an “Allegory” paragraph style in Scrivener, and in the Compiler style we use the fenced div syntax prefix=
n::: {custom-style='Allegory'} :::n
& suffix=n:::n
(n
means enter a return, done using option+return
in the edit box) which would generate a fenced div like so in the compiled Pandoc file:Pandoc will then attach a word style named “Allegory” to that paragraph in the output DOCX. You can either edit the style in Word, or edit your reference.docx to include this custom style, so it already styled when you open the DOCX.
Binding ⌘B etc. to Scrivener Styles
Most people have ⌘B & ⌘I key bindings well memorised for bold and italic. A cool thing about Scrivener Styles and macOS is you can rebind these keys so they toggle the Strong and Emphasis styles rather than bold and italic itself. To do this you go to
System Preferences ▸ Keyboard ▸ Shortcuts
, click the [+] button, select Scrivener.app and enter the name and key to make the following:Figure 6 — Rebinding macOS keys to use Scrivener Styles.
In the case of
Strong
and Emphasis
, there is no need to enter the full menu path to the Style as the names are unique, but you can also use the complete Format->Style->Emphasis
to make this entry explicit. More general instructions from Literature & Latte are available here. A 3rd-party tool that provides key rebinding and an incredible amount of additional control is BetterTouchTool. You would remap the keys in the following way in BTT:Figure 7 — Rebinding macOS keys to Scrivener Styles in BTT.
Working with Bookends Reference Manager
Bookends is an excellent reference manager for macOS which can be configured to output temporary citations for Scrivener in a format fully compatible with Pandoc. To set this up I’d first follow the excellent tutorial here:
To export your references as a file Pandoc can read (usually a BibTeX file) you can do tht manually from the Bookends GUI. However, you can do this automatically every day or so using this applescript, you can specify an output folder and comma-separated list of groups via command-line input. This script can also be run directly from Bookends Tools for Alfred. I would recommend setting the option to save a JSON instead of BibTeX as Pandoc parses the JSON ~3X faster when processing documents, and with a big reference database that can save quite a lot of time!
Minimal LaTeX Install
I prefer to use the minimal LaTeX installer found here: BasicTeX Installer (can install with brew:
brew cask install basictex
) — and for Pandoc’s templates to work I’ve determined the following additional packages are needed (installed easily with the command line tool tlmgr
that comes with TeX, or with TeX Live Utility):Pandoc Github Markdown Css
Troubleshooting
- If you only get a HTML file out, it normally means that pandocomatic could not read the metadata or find the
pandocomatic.yaml
file. Make sure you have the Pandoc Data Directory properly set up, that your metadata at the top of the compiled markdown looks correct, and check for errors in thescrivomatic.log
file that you should get every time you compile in Scrivener. - YAML metadata can be a bit fussy:
- Metadata keys are lowercase: titlenotTitle, pandocomaticnotPandocomatic etc.
- You must use spaces for indentation, not tabs.
- You should use “straight” not “curly” quotes for strings (use Scrivener’s straighten quotes function).
- Strings don’t strictly need to be quoted, but it is normally safer (for example if there is a colon in the string you must quote).
- You can validate your YAML online here, and read a quick tutorial of YAML here.
- I use a Meta-data paragraph style to wrap
---
around the Pandoc metadata front-matter, but you can just put it directly in the front matter yourself. Which ever way you do it, without---
around the metadata it will not be recognised, and you will again get a simple HTML output file. - Make sure there are no
.ruby-version
config files used by rbenv in the compile folder, or if there are that they are configured to use the correct Ruby version with pandocomatic installed…