Using Markdown

What IS Markdown?

To make our Writing Guide and other documents easier to maintain and share across formats, we create them with Markdown. This lightweight markup language lets authors write well-structured text once, then output it in multiple formats. It is ideal for writing educational materials because authors do not have to constantly reformat text for new platforms.

Markdown takes ~20 minutes to learn, and marked text still is easy to read. The same text can be converted to HTML5 for web pages, or Word documents for printed handouts. Groups of Markdown files can be combined into interactive online books.

There are several “flavors” of the original Markdown language standard, but it is not hard to switch between them. We use the GitHub “flavor” of Markdown (GHFM) because:

• GHFM is the lingua franca for GitHub.
• GHFM has some functions that other flavors do not have.
• There are more tools for converting GHFM into other formats.
• GHFM is nearly identical to the Markdown syntax used in R Studio's .rmd files.

 

Why Not Use MS Word or Google Docs?

MS Word & Google Docs are designed to produce polished print documents, and so they include hidden styling information that makes them hard to reuse. If you have ever converted a long Word document into a web page, or combined several documents into one, you probably have seen unpredictable changes in format. This happens because of the hidden styling information. Or, say you have created a long document and converted it to Word, then decide you want to change all 155 section headers from blue to red text in a different font. This chore could take considerable time, and some headers may reset to their earlier formats without warning.

How is Markdown better?

The philosophy behind Markdown is that most text is used and reused across multiple formats. Separating content authoring from publication makes it easier to reuse content or combine documents.

Markdown's format codes are not hidden. It is much easier to locate and remove formatting errors.

Markdown files are VERY small compared to .docx/.gdoc files. For comparison, a Markdown file for a 30-page set of workshop handouts would be <60KB; the corresponding Word file could be 3.8 MB (70x larger) or more.

Markdown files do not contain embedded images. They use an address to "call in" images when the document is rendered. This means one master set of images can be stored in a single location, and called into any Markdown document. If an image gets updated, every document or web site that uses that image will use the new version the next time the file is generated.

Converted Markdown documents have consistent styling tags for that document type. This greatly reduces time spent reformatting converted documents.

Markdown is truly cross-platform compatible. The same file can be edited on a Mac, a PC, and a Linux machine, and never have file compatibility problems.

Plenty of Markdown tools are available for free. This greatly reduces the accessibility barrier.

 

How to Get Started

Unlike HTML, Markdown does not require any special code or starting text at the beginning of a new document. The only requirement is that it be a plain text file with .md as the extension. To interconvert between plain .md files and .rmd files (R Studio Markdown format), simply add or remove the "r" in the file extension.

There are many ways to write Markdown files.

• Use your computer's plain text editor. If you need to use documents in many different places, output them in multiple formats, or are not sure where they will go, writing them in a standalone text editor is probably easiest.
• Write them entirely inside another program. For example, R Studio includes a fairly good plain text editor. If you plan to use .md files mostly in the context of R Studio, it makes sense to write the text files there too.
• Write .md files in a browser. There are several browser-based Markdown-aware text editors on the web. We've listed some in the Resources section.

Which authoring tools will work best for you depends on your personal preferences, and how you plan to use the files. You may end up using some of all three methods. Markdown behaves slightly differently in different editing environments. One probably will feel more comfortable than the others, and become your preferred editor.

 

Our Resources

Resources	Links
Short Guide to Using Markdown	R/MD file;   DOCX file
File Conversion, Step by Step	R/MD file;   DOCX file
More Tools for Markdown	DOCX file

 

Where to Learn More

1. WHY and HOW to write well-structured, reusable texts