Table of Contents
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:
- It has an open specification. No more sharing slow-opening, proprietary document formats like Microsoft Word or Adobe PDFs. Very portable docs.
- 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.
- It's straightforward to learn and expressive. Writing
# My Titleand
## My Titleis visually easy to spot and easy to
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.
|Tool||Context of use case||Pros||Cons|
|GitHub ||My first markdown experience||Built into Github and free from PDFs and Word docs. Also, syntax highlighting||The UX while navigating interlinked markdown files is awful|
|react-markdown||I wanted to build a markdown-powered blog||All the flexibility/power you need. Easy to understand.||Everything was custom-written, self-hosted|
|GitBook||Greenfield project at work||Nice UI/default theme, search. Can publish to PDF (had to once!)||Requires hosting|
|GitHub Wiki||Greenfield project at work||No need to host by self.||Not the best UX, search is lacking|
|GitHub Pages||Greenfield project at work||No need to self-host, Jekyll is built-in, themes are easy to use||As 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!
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
<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<PopQuestionquestion="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.
"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!