- I'm running some text files written in Markdown through Pandoc to get html, but it renders the tags strangely with weird line breaks and white space in tags, so I've been running a few sed commands.
- Pandoc is the swiss-army knife for converting files from one markup format into another. The Vim plugin for markdown is young and basic in comparison to.
I'm a writer and I used Vim as my main text editor for years. Pencil & Goyo are great - I also used vim pandoc as well (you'll also be wanting pandoc syntax for highlighting as well). I also think the OneDark theme for vim is particularly good for markdown as well.
As you might know,I’m writing a book calledCompiling to Assembly from Scratch.Recently Itweetedabout my book-writing setup, andthere was a lot of interest in thedetails of my setup.I’m only halfway throughwith writing the book (or, so I think),so my setup will likely to change as I go.But here it is, anyway.
A screenshot:
I’m on macOS, so I’m using the nativefull-screen split functionality.On the left, I have Terminal.app running Vim,and on the right, I have Preview.appshowing—ahem—a preview.Both apps ship with macOS.
I’m writing the book in Markdown,then use Pandoc to convert it to PDF and EPUB.
Pandoc
I use Pandoc as myMarkdown processor.It is a great tool, written in Haskell, and availablefrom most package managers.It converts from and to many different document formats.Still, I am mainly interested in PDF and EPUB for my book.
While Pandoc supports CommonMark and GitHub-flavored Markdown,I am using the Pandoc dialect of Markdown.It has support for many extensions:footnotes, different styles of tables, math, etc.
For example, the table style that I’m using in thescreenshot allows changing column width andproportions by changing the Markdown column widths.
Although I’m using Make to run Pandoc, here’san equivalent shell command:
By default, to produce PDF, Pandoc converts the document to LaTeX first, then calls pdflatex to produce the PDF.Howerver, with --pdf-engine=xelatex I opted in to useXeTeX together with xelatex command to produce PDF.
First, XeTeX allows to use Unicode characters in the sourceof the document. I’m quite accustomed to enteringen-dash and em-dash and other special charactersusing option-key shortcuts on macOS.Second, XeTeX allows to use arbitrary system’s fonts,and that’s what I did with Palatino.
I’ve set up some preliminary paper size and marginand LaTeX documentclass, but I will definitely betweaking them before releasing the book.
Producing EPUB with Pandoc also works fine,but I’m sure I will do more tweaking thereas well:
Figures
I’ve been using draw.iofor various diagrams at work and for this blog.But for the book, I wanted to use something open-source,something reliable, something that would notincredible journey me over halfway through writingthe book, leaving me without a critical tool.
So I started searching, and imagine my surprise whenI learn that draw.io is, in fact,open-source.That was a relief!
I’ve been using one big draw.io document so farand I exported individual figures to SVGby using export selection feature.
SVG is well supported with EPUB, since EPUBis just glorified HTML and CSS under-the-hood.For PDF output, Pandoc requires to installlibrsvg (written in Rust) and handlesthe conversion transparently.
Makefile
Even though my book right now is written in a singleMarkdown file, I started using Make anywayfrom the get-go.I’m using my system’s build-in GNU Make.Here’s my Makefile:
A few things that are worth mentioning:
Makefile itself is a dependency of some rules.This is done so that if I change afont (or some other Pandoc flag),Make would pick it up and rebuild the target.
The list of all figures (*.svg glob)is a dependency as well, to make sure that the bookis rebuilt when a figure is updated.
The build artifacts are stored in the output folder,which is an order-only prerequisite(specified with “| output” syntax).This is useful because we don’t care about the timestampof this directory, only that it exists.
Running “make open” uses macOS open command(similar to xdg-open on Linux) to openthe PDF in Preview.app.If it is already open, the Preview.app will refreshthe existing window.
I have a special “.PHONY: phony” rule, thatallows me to write:
Instead of the usual:
Note that this trick can slow down huge Makefiles.
To be honest, this is mostly just me flexing myknowledge of Make, rather than anything useful.A small build script could do just as well.
Vim
I am using the version of Vim that ships with macOS,with minimal tuning.One ~/.vimrc option worth mentioning hereis virtualedit:
It allows to move the cursor past the last character.If you insert a new character there,it is automatically padded with spaces.It is easier to see it than to explain it:
This is very useful for dealing with tables and much more!In fact, I use this option for all my editingin Vim for about a decade now.My first programming environment wasTurbo Pascal, and this is exactly how thecursor works there, which I grew accustomed to.
Vim Pandoc Conceal
When I open the editor I write :!make opento open the preview, and then use :!! to repeatthat command.In fact, I have a shortcut that mapsspace bar to save current file and run previous command:
This save-file-and-repeat-last-command command isis useful for other things, for example, runningtest suites.
And that’s about it.When I finish my book, I will write a new blogpost about any significant changes to this process.■
⁂
By now, you have probably heard that
I’m writing a book about compilers!
Vim Pandoc Tables