Table of Contents

• The Past
• The Present
• The Future

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.

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.

MDX

Much like you can write HTML in a markdown document, you can write JSX within an MDX document. MDX is a nifty syntax extension for markdown that enables including React components within markdown. Imagine being able to include components like <FunFact/>, <Chart/>, <Video/> and <PopQuestion/> to increase interactivity of your plain-text documents. The components can encapsulate state, styling and interactivity in a simple API for authors. Let's look at what a <PopQuestion /> might look like!

<PopQuestion
  question="Who originally proposed MDX?"
  answer="Guillermo Rauch (@rauchg)"
/>

Click below and see the interactivity provided by the source code above. Simple isn't it?

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. Given a library of a few React components, an author could have the power to author fairly engaging documents with minimal code.

Remark

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!