Universal Rich Documentation Platform

Vuepress Has Done It

Rob Muhlestein
Sep 7, 2018 · 2 min read

I’m still surprised how many technical writers still have not discovered Vuepress. It is singularly the best rich documentation platform I have ever seen. Every detail has been accounted for including things as simple as hiding the configuration away in a hidden directory so the primary focus is the content.

But the overwhelming reason every technical and educational writer must learn it is the ability to create rich interactive content that—wait for it—allows embeddable Vue components in the Markdown.

If there ever was a solid empirical example of why the Vuejs approach of simply using HTML (instead of the deformed monster that is React JSX, or even worst, that deformed monster’s bastard child MDX) this is it. In fact, it is very validating watching the entire React sheeple community hit this very sobering, very insurmountable obstacle caused by React’s terrible decision to use JSX in the first place. What are they going to do, keep putting X’s on the end of all the standards that already exist as they infect them with their diseased design? Reminds me of the XML insanity (which JSON fixed) or the CoffeeScript insanity, which, the JavaScript standard fixed. 🤣

CommonMark (the closest thing to a standard for Markdown) allows the embedding of HTML and therefore Vuejs components. React simply can’t—and will never be able—to do that. Standards matter.

What about separation of concerns?

We are not talking about a full web application here. We are talking about adding small components to add interactivity to a document, not an application.

I have to laugh out loud at all the Gatsby trending out there given the amount of unnecessary bloat and complexity when compared to Vuepress. It is fair that Vuepress has one goal in mind, amazing, interactive documentation while Gatsby is trying to be all things to all static-site people, which, again, is at the core of the problem.

Evan (the brilliant) has nailed the closest thing to a standard for a dynamic documentation format the world has ever seen. Congratulations and THANK YOU!

Rob Muhlestein

Written by

/^((Found|Teach|Hack)er|(Men|Jani)tor|C\w+O)$/ 🌎 skilstak.io 💥 robs.io

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade