I personally am a huge fan of pandoc
.
Pandoc is the "swiss-army" knife tool of format conversions:
- Its core source input format supported is
Markdown
(including any of the major MD "dialects" such as the flavors of GitHub and PHP plus several special extensions). Other input formats are: HTML
, rST
, Textile
, DocBook XML
, MediaWiki
.
- As output formats it supports:
ConTeXt
, LaTeX
, PDF
and Beamer PDF
(albeit requiring LaTeX in the background), MediaWiki
, DOCX
, DocBook
, rST
, Textile
, ASCIIDoc
, texinfo
, org
(Emacs Org-mode), S5
(HTML slides), Slidy
(HTML slides), Slideous
(HTML slides), ImpressJS
(HTML slides), DZSlides
(HTML slides), HTML
, HTML5
, EPUB
, EPUB3
...and: manpage
(GROFF manpage) and ODT
(OpenDocument Text).
Are you still with me? Good.
Did you notice the last two, manpage
and ODT
?
Well, these are the two output formats which I personally "abuse" as intermediate formats in order to arrive at PDF for final documents when I do not want LaTeX involved.
I've automated my workflow and process chain with the help of a Makefile. So I just need to type make mydoc.latexpdf
, or make mydoc.odtpdf
, or make mydoc.manpdf
. The Makefile is set up to look for an input of mydoc.mmd
, and then it sets the appropriate commands in motion: pandoc
to create the PDF directly (which in the background first converts to LaTeX and then runs pdflatex
itself), ODT or manpage. Then the next command is to create the final format:
For my .odtpdf
target it runs LibreOffice in headless mode. Here are the basic command lines I use for the (I'm on OS X, so for Linux or Windows you'll have to adapt paths accordingly). Attention, command is in Makefile syntax -- cannot be directly used in Shell without prior adaption:
(cd /Applications/LibreOffice.app/Contents/MacOS; \
./soffice "-env:UserInstallation=file:///tmp/LibO_Conversion__$(USER)" \
--headless \
--convert-to pdf:writer_pdf_Export \
--outdir $(CURRDIR)/$(FINAL) $(CURRDIR)/$(BUILD)/$(subst .odtpdf,.odt,$@) ; \
cd - ; )
For my .manpdf
target it uses man -t
to create PostScript from Pandoc's manpage output file, then uses Ghostscript to create the PDF. It therefore runs:
man -t <pandoc's manpage output file> \
| gs -o ${HOME}/<pandoc-sourcedoc-name>.pdf -sDEVICE=pdfwrite -
Customize the look'n'feel of your ODT output
The non-LaTeX path to PDF via ODT is the most "sexy" for me...
- ...because Pandoc knows how to apply some nice personalized styles to a target ODT if only these styles are properly defined in a
myreference.odt
! (These styles will of course then transfer to the PDF too.)
I can then run the Pandoc command (via Makefile or in the Shell) to create an ODT to my likings, complete with the font faces, sizes and colors I prefer, with the page sizes and page headers, footers or backgrounds I defined (again: Makefile syntax!):
pandoc \
--toc \
--toc-depth=4 \
--to=odt \
--chapters \
--filter=pandoc-citeproc \
--standalone \
--reference-odt=$(RESOURCES)/myreference.odt \
--from=markdown+mmd_title_block+pipe_tables+grid_tables+tex_math_dollars+raw_tex+footnotes+inline_notes+citations+link_attributes \
--bibliography=$(RESOURCES)/my.bib \
--csl=$(RESOURCES)/kp.csl \
--number-sections \
--output=./$(BUILD)/$@ \
$<
The --from=markdown+...+...+
parameter tells Pandoc to accept several Markdown syntax extensions which I like to use in my MD source files.
The sweet secret to get the styles in the ODT document lies with the --reference-odt=/path/to/myreference.odt
command line parameter.
The ODT output works with references and bibliography even (if your Markdown input is properly written for this)!
Using Windows?
In principle, this workflow should work on Windows too, because Pandoc also runs on Windows. I have run Pandoc on Windows before, but I have not myself setup a completely automatic workflow, first "Pandoc
: Markdown -> ODT", then ".\soffice
: ODT-> PDF" based on a Makefile here, though...
But you may want to explore another path on Windows:
- create a DOCX output from Pandoc first;
- then convert the DOCX to PDF (automatically or interactively via WinWord).
Yes, you can also customize the styles of the DOCX output files by using the --reference-docx=my-reference.docx
switch. Just create a my-reference.docx
file first which uses exactly the styles you want. Pandoc will then extract these from the reference doc and apply them to the output DOCX it generates!
From there, you can look how to convert the intermediate DOCX file to PDF. This can also be done automatically: you may also want to consider OfficeToPDF.exe. It is hosted on CodePlex, licensed with the Apache 2.0 License and available in binary and in source code.
Finally: be sure to use the latest and greatest version of Pandoc (currently v1.17.0.3 or later) -- there have been a lot of features added in recent months, esp. when it comes to DOCX output!