If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert between the following formats:
(← = conversion from; → = conversion to; ↔︎ = conversion from and to)
Vim与Pandoc 既然现在有了panodc这个神器，那么大部分的文本编辑操作我就可以在Vim中进行了，而不需要去使用那个无比臃肿的word了，配合Vim强大的定制功能，我就能配置出一个功能完善的pandoc写作环境了。. See full list on jamesbvaughan.com.
- This is a curated list of some of the most useful third-party software that extends pandoc’s capabilities. For a more complete list, see the Pandoc Extras wiki page. GUI PanWriter is a Markdown editor with live preview that can import and export using pandoc.
- Pandoc understands a number of useful markdown syntax extensions, including document metadata (title, author, date); footnotes; tables; definition lists; superscript and subscript; strikeout; enhanced ordered lists (start number and numbering style are significant); running example lists; delimited code blocks with syntax highlighting; smart quotes, dashes, and ellipses; markdown inside HTML.
↔︎ Markdown (including CommonMark and GitHub-flavored Markdown)
↔︎ reStructuredText
→ AsciiDoc
↔︎ Emacs Org-Mode
↔︎ Emacs Muse
↔︎ Textile
← txt2tags
↔︎ (X)HTML 4
↔︎ HTML5
↔︎ EPUB version 2 or 3
↔︎ FictionBook2
→ GNU TexInfo
↔︎ Haddock markup
↔︎ roff man
→ roff ms
↔︎ LaTeX
→ ConTeXt
↔︎ DocBook version 4 or 5
↔︎ JATS
→ TEI Simple
↔︎ OPML
↔︎ BibTeX
↔︎ BibLaTeX
↔︎ CSL JSON
↔︎ CSL YAML
↔︎ Microsoft Word docx
↔︎ OpenOffice/LibreOffice ODT
→ OpenDocument XML
→ Microsoft PowerPoint
Vim-pandoc Pdf
↔︎ Jupyter notebook (ipynb)
→ InDesign ICML
↔︎ MediaWiki markup
↔︎ DokuWiki markup
← TikiWiki markup
← TWiki markup
← Vimwiki markup
→ XWiki markup
→ ZimWiki markup
↔︎ Jira wiki markup
→ LaTeX Beamer
→ Slidy
→ reveal.js
→ Slideous
→ S5
→ DZSlides
← CSV tables
Vim Pandoc Tables
→ custom writers can be written in lua.
→ via pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, prince, context, or pdfroff.
Pandoc understands a number of useful markdown syntax extensions, including document metadata (title, author, date); footnotes; tables; definition lists; superscript and subscript; strikeout; enhanced ordered lists (start number and numbering style are significant); running example lists; delimited code blocks with syntax highlighting; smart quotes, dashes, and ellipses; markdown inside HTML blocks; and inline LaTeX. If strict markdown compatibility is desired, all of these extensions can be turned off.
LaTeX math (and even macros) can be used in markdown documents. Several different methods of rendering math in HTML are provided, including MathJax and translation to MathML. LaTeX math is converted (as needed by the output format) to unicode, native Word equation objects, MathML, or roff eqn.
Pandoc includes a powerful system for automatic citations and bibliographies. This means that you can write a citation like
and pandoc will convert it into a properly formatted citation using any of hundreds of CSL styles (including footnote styles, numerical styles, and author-date styles), and add a properly formatted bibliography at the end of the document. The bibliographic data may be in BibTeX, BibLaTeX, CSL JSON, or CSL YAML format. Citations work in every output format.
There are many ways to customize pandoc to fit your needs, including a template system and a powerful system for writing filters.
Pandoc includes a Haskell library and a standalone command-line program. The library includes separate modules for each input and output format, so adding a new input or output format just requires adding a new module.
Pandoc is free software, released under the GPL. Copyright 2006–2020 John MacFarlane.
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:
Vim Pandoc Conceal
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.
Vim Pandoc Pdf
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.
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!