Making Markdown Usable!

Table of Contents

The Past

If you're like me, you've used markdown for a long time. You may have first seen it on GitHub or found it in the source code of one of your favorite libraries. I remember when I first used markdown, I instantly saw the value proposition. In my view, the three biggest pros for markdown are:

  1. It has an open specification. No more sharing slow-opening, proprietary document formats like Microsoft Word or Adobe PDFs. Very portable docs.
  2. It has a lightweight markup language that is human-readable. The syntax visually resembles the corresponding HTML and doesn't require a rich text editor to edit/review/display.
  3. It's straightforward to learn and expressive. Writing # My Title and ## My Title is visually easy to spot and easy to grep for.

If you're also like me, you've tried different publishing solutions over the years. Here are some of the platforms I've used with the context of why I chose them. The pros and cons aren't comparative. Instead, they are the progression of requirements in chronological order.

ToolContext of use caseProsCons
GitHub README.mdMy first markdown experienceBuilt into Github and free from PDFs and Word docs. Also, syntax highlightingThe UX while navigating interlinked markdown files is awful
react-markdownI wanted to build a markdown-powered blogAll the flexibility/power you need. Easy to understand.Everything was custom-written, self-hosted
GitBookGreenfield project at workNice UI/default theme, search. Can publish to PDF (had to once!)Requires hosting
GitHub WikiGreenfield project at workNo need to host by self.Not the best UX, search is lacking
GitHub PagesGreenfield project at workNo need to self-host, Jekyll is built-in, themes are easy to useAs a React developer, I don't like templating languages

Looking back, I could have done a better job of vetting potential alternatives before committing to an option. The way I've processed this journey is: each stage served the purpose of growing my skills as a developer. Each platform provided an opportunity to learn something. I learned how to buy a domain, how to write maintainable CSS, and even how to use Ansible to configure a server. At the end of the day, all of these docs were written in markdown and are portable. So, no vendor lock-in!

The Present

Today, I am interested in having a bit more control of markdown documents. More precisely, I'm interested in using specific plugins that can enhance markdown by programmatically altering the abstract syntax tree. This is enabled through processors and plugins like remark, MDX and rehype. These processors enable writing impressive webpages with plain-text documents.


Much like you can write HTML in a markdown document, you can write JSX within an MDX document. MDX is a nifty markdown extension that lets you include React components within your markdown. You can embed React components (like below) within your MDX document. Imagine having components like <FunFact/>, <Chart/>, <Video/> and <PopQuestion/>. They encapsulate styling and interactivity in a simple API for authors. See a snippet below for an example.

// This kind of code can be embedded directly in an MDX document
question="Who originally proposed MDX?"
answer="Guillermo Rauch (@rauchg)"
// See below for an example of the React component above ^
// Click it!!!

Question: Who originally proposed MDX?

With these embedded React components you could even query external APIs. Imagine having interactive React components displaying live data, all contained within an MDX document. It's powerful!


Remark provides a whole suite of plugins worth checking out. I've used them to autogenerate a table of contents, add attributes to the headings (for anchor links), add syntax highlighting and much more.

The Future

"If you optimize everything, you will always be unhappy." - Donald Knuth

One of the first lessons in engineering and computer science is that you can't optimize for everything. Markdown is human-readable plain text, and consequently, it can easily be checked into your version control, aggressively peer-reviewed, grepped, diffed, statically compiled and displayed on responsive screen sizes. One of the limitations of this plain-text format happens when you want to include diagrams and quickly add attachments. For features like that, we often end up losing the original properties of plain text and end up with platforms like Confluence and Microsoft Word.

So, I'm interested in seeing what kinds of experiences are possible while staying true to the design decision to use plain text. Stay tuned to hear more!