Converting Markdown to Formatted

Converting Markdown to Formatted

Markdown is a markup language to imply formatting in documents, which can then the converted to a formatted document such as HTML or Microsoft Word. It allows a user with any text editor, such as EMACS, Notepad, or vi, to create a flat ASCII file with some formatting information. It can be read as is, or imported to make a “pretty” version.

I’ve ued Markdown a number of ways. A lot of web documnts I’ve created were first drafted in Markdown. In a way, it reminds me of hitting “reveal codes” in Old School WordPerfect. You can see exactly where the formatting begins and ends, and percisely put individual characters inside or outside those bounds.

This document is not intended to teach you how to use Markdown–there are plenty of sites out there for that purpose. Instead, I wan to show why one might use Markdown, and how to move it from a text file with markup to something “pretty.”

Why Use Markdown

• Human Readable While there are other markup languages that have some of the advantages below, most of the “codes” for Markdown are simple, and suggest what the formatting is. You could simply cat (type for Windows and VMS folks) a Markdown file. Even if you don’t know that putting *an asterisk around text* means italics, you can infer that this word is emphasized in some fashion.
• Portability Since Markdown files are just simple text files, they can be read on pretty much any operating system, such as MacOS, other UNIX or UNIX-like operating systems, Windows, and plenty of historical operating systems.
• Choice of Tool Pretty much any text editor, such as EMACS, Notebad, or vi, read and write text files. If you are already using one of these, they can fit right into your workflow. Other tools, such as Microsoft Word, will export a text file, though it will not have any formatting added by Word. There are stand-alone applications that read and write Markdown, and plug-ins for tools like Word.
• Standard RFC 7763 and RFC 7764 govern Markdown, meaning no one company controls it.

Markdown versus Other Markup Language

One advantage of Markdown is it more human readable than other formats. Consider this Markdown text:

# Text Example

This text is written in Markdown. I can do *italics* or **bold**. I can make a list:

* Item One
* Item Two
* Item Three

The most common markup language is HTML. This is the same text in that format:

<h1 id="text-example">Text Example</h1>
<p>This text is written in HTML. I can do <em>italics</em> or <strong>bold</strong>. I can make a list:</p>
<ul>
<li>Item One</li>
<li>Item Two</li>
<li>Item Three ```</li>
</ul>

The TeX family is another, much older format. Here is the same text in LaTeX, a common variant:

\hypertarget{text-example}{\%
\section{Text Example}\label{text-example}}

This text is written in LaTeX. I can do \emph{italics} or
\textbf{bold}. I can make a list:

\begin{itemize}
\tightlist
\item
  Item One
\item
  Item Two
\item
  Item Three
\end{itemize}

All of this will produce the same text, with the same formatting. They are also all simple text files. The key difference, in my opinion, is that the Markdown version can be read easily as-is.

How to Read Markdown Files

Markdown files usually have the extension .md or .markdown. As previously metioned, they’re just text files. They can be read with anything that can read a one:

• The cat command in UNIX
• The type command in Windows or OpenVMS
• Any text editor such as EMACS, Notepad, or vi
• Most word processors, such as Microsoft Word, can import a text file

Reading it raw, as described above, will let you read the text, but not get formatting. Fortunately, the nature of the markup allows it to be read pretty readily in raw form–you just have to imagine *the itallics* for yourself.

Beyond that, there are a variety of tools that not only support Markdown, but will present it formatted for your device–you don’t have to imagine the itallics. This will let you write in Markdown, then get a “preview” of the formatting. You can print that (if required), export it to a different format, or even copy the text, with formatting, and paste it into another application.

Below are just a sample of some easy options to view a Markdown file. The focus is mostly on free, and ideally web based options. There are scores of programs that will support Markdown files in some fashion–too many to list here. This is just a starting point.

Pandoc

Pandoc does not let you view a file directly, but will convert among a variety of formats, such as Markdown, HTML, RTF, and Microsoft Word. If you wanted to convert foo.md to HTML and ouput it to foo.html, you would type:

pandoc -f markdown -t html -o foo.html foo.md

The resulting file can be viewed in any browser. Likewise, to produce foo.docx for Word:

pandoc -f markdown -t docx -o foo.docx foo.md

Pandoc is handy for converting not just from Markdown, but other formats:

pandoc -f html -t docx -o foo.docx foo.html

Or even getting from something else to Markdown:

pandoc -f docx -t markdown -o foo.md foo.docx

It does not, in and of itself, allow you to view a formatted file. But it is a nice Swiss army knife for managing files. It can also be integrated into other workflows for file conversion.

Dillinger

Dillinger is an online Markdown viewer and editor. It allows you to view the Markdown in one Pane, and the resulting text in another. Files can be uploaded, and saved to common cloud storage sites. It’s open source, and you can host one youself. Text can be exported as HTML or as a PDF.

Simplenote

Simplenote is a free, online note taking application. It’s similar to Evernote or OneNote. At first glance, it would appear to have, at best, limited formatting options. However, a note can be tagged as a Markdown note.

A “preview” button lets you see it as formated text.

In addtion to the web application, there are also official apps for desktop opperating systems (MacOS, Windows, and Linux), iOS, and Andriod. There are also third party interfaces into it, such as simplenote2.el, which allows notes to be read and edited inside EMACS.

I tend to use the iOS application on the phone, and either the browser or simplnote2.el on laptops/desktops.

Visual Studio Code

I’ve mentioned most text editors can read and write Markdown files, as they are just text files. Most will not show you the resulting formatting–at best, you might find something like Markdown Mode for EMACS, which, if on a supported terminal, will bold or itallicize text in your buffer (this is what I tend to use to write Markdown text).

Microsoft offers Visual Studio Code, a text editor that has a preview option for Markdown. This lets you see the output, as well as copy and paste to other applications.

QLMarkdown

MacOS has, for quite some time, a feature called Quick Look. This allows previewing a file in Finder (The file manager) simply by selecting a file and pressing the space bar. It works for most file types…except, by default, Markdown.

There are several plug-ins that add that functionality to Finder. The one I’ve used is QLMarkdown. This is a simple “just works” application. There are others out there I cannot speak to.

Summary

Markdown is a useful tool when wanting to creating lightweight documents that can be “upgraded” to include richer formatting. I use it for this blog (this post itself was writen using Markdown), and my personal notes. Regardless of what I’m creating a document on–my MacBook, phone, or some retro system I’m connected into via an ssh session, it’s there.

This is a “preproduction” post, testing out the end-to-end system of the blog.