Stimpunks Foundation

Mutual Aid and Human-Centered Learning for Neurodivergent and Disabled People

Donate
Volunteer
Get Help
Markdown Bible cover

Markdown

Markdown cover art resembling a Bible

Markdown provides a simple way of including formatting in plain text files. Originally developed for writing for the Internet, Markdown is also super useful for any type of writing where the author wants to include formatting in plain text.

Markdown isn’t so much a language as it is a writing method. Markdown greatly simplifies the formatting for rich text elements, such as bold and italics, and web-friendly doodads, such as links to the Internet, using plain text. The fancy-pants word for this is syntax. Put simply, Markdown makes it deceptively simple to write for the web and rich text word processors with plain text. It is a game changer, and by the end of this book, you are going to be a pro at it.

Markdown
Home » Field Guide » Communication » Markdown

Our communication stack — WordPress, P2, and Element — speaks Markdown. Taking notes in Markdown allows you to paste them directly into the tools in our stack, complete with nice formatting.

Learn Markdown:

Screenshot of the Markdown-based editor Ulysses showing a simple Markdown document consisting of a header and a list.
Screenshot of the Markdown-based editor Ulysses showing a simple Markdown document consisting of a header and a list.

There are many great Markdown editors. Ryan likes Ulysses, which is included in our Setapp for Teams subscription. See our Software page for more recommendations.

Why Markdown rocks:

Markdown remains an excellent solution for publishing to the Internet. Authors can write blog posts, articles, and anything else for publication in the HTML format while avoiding most of the brackets, symbols, and other hieroglyphics involved with coding HTML. The text is easier to read, edit, and, most importantly, write.

There is no reason to make thought capture harder than it already is. In fact, the very best thought-capture routines are those that have the least friction between the thought and the act of writing it down. We even wrote the initial outline for this book in Markdown.

As we will show shortly, the Markdown syntax for standard outline elements, such as headings and bullets, is extremely simple to both write and read. Markdown is useful even for text that you never plan to publish on the web. It can be great for taking notes in meetings, conference calls, or in any situation where you need to get text down quickly. The simplicity of the syntax has another benefit—you can use whatever tool is handy: computer, tablet, or phone.

Markdown

This book began as a study of authors who we saw as “teachers” of the Markdown writing syntax. Markdown is a “plain text” writing syntax that uses common typographic symbols to indicate text styling. For example, bold text in Markdown is represented by **double asterisks** around the phrase to appear in bold type. In 2004 John Gruber, the inventor of Markdown, pitched it as a simpler way of writing for the web; an author would write in the Markdown shorthand and then use a computer script to turn that Markdown text into HTML. In the years since, Markdown support has been added to a number of writing applications. If you’ve used an app like Evernote, Scrivener, Ulysses, or Bear, you’ve likely bumped into Markdown. In many web writing contexts, it’s a popular and easy-to-learn writing technology.

At the 2013 Computers and Writing Conference, we (Derek and Tim) started talking about the broad Markdown affinity space: podcasts, blogs, self-published books, and social media conversations. We were particularly interested in the absence of these conversations within our field. How could a nearly ten-year-old writing technology continue to grow in professional and enthusiast spaces but also be largely absent among those who teach and research writing?

To answer this question, we designed a study in which we would interview several of these influential Markdown “teachers.” We mapped the Markdown affinity space, prioritizing those who had a significant audience that spanned multiple platforms, including blogs, podcasts, books, and Twitter feeds. In particular, we were interested in writers within the Markdown affinity space who published texts written in Markdown, taught users how to use Markdown, and made recommendations about Markdown-focused software.

When we started to analyze our data, however, we realized that this wasn’t a project about Markdown. Instead, we saw that the interviews offered insights about broader writing practices and software preferences. These writers were interested in and talked in detail about software-mediated approaches to writing practices—what they called “workflows.” We began to identify and trace a practice that we saw as “workflow thinking,” which we introduce in this book. To build and contextualize our macro concept of workflow thinking, we offer the cases of three writers.

Writing Workflows | Introduction

Unlike cumbersome word processing applications, text written in Markdown can be easily shared between computers, mobile phones, and people. It’s quickly becoming the writing standard for academics, scientists, writers, and many more. Websites like GitHub and reddit use Markdown to style their comments.

Formatting text in Markdown has a very gentle learning curve. It doesn’t do anything fancy like change the font size, color, or type. All you have control over is the display of the text-stuff like making things bold, creating headers, and organizing lists.

If you have ten minutes, you can learn Markdown!

Markdown Tutorial | Lesson 1

Plain text doesn’t change. Fifty years from now, you’ll still be able to open a plain text file. Until we all have squiggly tentacles on our faces and communicate telepathically, plain text will be a thing.

What about conversion software? Let’s say a tiny black hole swallows up every Markdown converter on the planet. You still have nice, clean plain text.

With Markdown, you don’t entrust your writing to 50,000 corporate shareholders, the companies they control and whatever features they “sunset” or add.

You control your destiny because, yes, you guessed it: It’s plain text.

Why I Use Markdown, & You Should Too – Portent

Since its introduction in 2004, Markdown has enjoyed remarkable success. Markdown works for users for three key reasons. First, the markup instructions (in text) look similar to the markup that they represent; therefore, the cognitive burden to learn the syntax is low. Second, the primary arbiter of the syntax’s success is running code. The tool that converts the Markdown to a presentable format, and not a series of formal pronouncements by a standards body, is the basis for whether syntactic elements matter. Third, Markdown has become something of an Internet meme, in that Markdown gets received, reinterpreted, and reworked as additional communities encounter it. There are communities that are using Markdown for scholarly writing, for screenplays, and even for mathematical formulae. Clearly, a screenwriter has no use for specialized Markdown syntax for mathematicians; likewise, mathematicians do not need to identify characters or props in common ways. The overall gist is that all of these communities can take the common elements of Markdown (which are rooted in the common elements of HTML circa 2004) and build on them in ways that best fit their needs.”

RFC 7764 – Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations

Further reading,

Plain Text
⌨️ Written Communication Is the Great Social Equalizer
Workflow Thinking
Stack