Command-line document conversion tools for writers

Today, we have ample tools available for editing memos, letters, essays, books, presentation slides, and other documents on our computers. This can be both an advantage and a disadvantage: on the one hand, if you don't like a piece of software, you can simply move on to another one any time; on the other hand, a lot of these tools, especially proprietary software, are fully compatible with their own formats only. As a consequence, the more documents you have created with such a program, the less likely switching over to another solution will be possible without investing significant time, energy, and even money. This phenomenon is called vendor lock-in.

For this reason, I use free software or open source software with open formats whenever possible so that I'll be able to easily find a tool to view and modify them in the future.

In this article, I'll explore two solutions that meet my criteria, namely Markdown (with Pandoc) and Org-mode.

Markdown originally started as "a text-to-HTML conversion tool for web writers," as described by its creator John Gruber. Nowadays, it can be considered as a markup language, which emphasizes simplicity. It allows you to insert rich text into your documents such as headings, text with emphasis (using bold and italics typefaces by default), hyperlinks, images, lists, quotes, and code snippets. Some versions of Markdown have additional elements: GitHub Flavored Markdown, for example, also supports tables, syntax highlighting for markup and programming languages, task lists, emoji, and more.

One of the best parts of Markdown is that a document of this format is stored as plain text. In other words, it can be opened with a simple text editor, which can be found on virtually all computers and handheld devices. In contrast, let's say you happen to be using a device that only has a simple text editor installed and you're trying to open a DOCX file. Although you can open it, the result to us is an unreadable mess, because what you're looking at is a binary format that is intended for a piece of software (in this case, Microsoft Word) to read.

Another benefit you can gain from Markdown is that it separates writing content from design. Have you ever been distracted by the realization that your text doesn't look like what you want, so you decided to stop mid-sentence and adjust its formatting? If you use a WYSIWYM approach like Markdown with Pandoc, then that will never happen again. Instead, you write down whatever ideas are on your mind in the source file (which is the plain text file using the Markdown format here), and only then convert it to the output format and adjust its appearance until you see fit. If you're used to programs using the WYSIWYG approach, this may seem a little strange at first sight, but in the long run, especially in the case of longer documents, your writing experience will be smoother, with fewer distractions.

When you have finished writing your source file in Markdown or ready to preview it, there are plenty of options when it comes to conversion to other formats, but I like to use Pandoc. It supports a plethora of formats, including PDF (through LaTeX), HTML (with CSS), EPUB, OpenDocument Text (ODT), and Office Open XML (DOCX). It integrates well with Vim thanks to the plugin vim-pandoc, but you can use it independently of any editors, too. (Also, I always keep the source file, even if the document is complete and has been exported to another format so that I won't have to start over if I need a portion of it in another document or I need to update it for some reason.)

Another excellent piece of software is Org-mode. It is "for keeping notes, maintaining To-Do lists, planning projects, and authoring documents with a fast and effective plain-text system," as described on the project website. Just like Markdown accompanied with a conversion tool, Org-mode allows you to write a source file using its own syntax, which is also human-readable and supports rich text, and export it to other output formats, such as PDF (through LaTeX), HTML (with CSS), and OpenDocument Text.

Since Org-mode is part of GNU Emacs, you'll definitely need to have Emacs installed for conversion. However, since its source file is plain text, you can open it with any editor. If you don't want to touch Emacs at all (other than setting it up once, which is necessary), you can find frontends such as vim-orgmode, which allows you to use the most common features of Org-mode inside Vim.

Both Markdown with Pandoc and Org-mode make writing documents a lot easier. Both provide ways to start with a plain text file that can be opened with basically any editor, they separate content from design, allowing you to focus on the ideas that you want to write down, and they support conversion to a lot of formats, most of which are open formats. This way, you won't have to stick to a single format again that requires you to use one specific application for your needs.

Do you use Markdown with Pandoc or Org-mode? If so, what do you like the most about them? Do you use any other open source alternatives? Share them in the comments.