UnMarkDocs: Better Markdown for your documentation
Miguel Piedrafita Jun 19 Originally published at blog.miguelpiedrafita.com on Jun 19, 2018
👋 Hi! I’m Miguel Piedrafita, a 16-year-old software developer, and I’ve spent a year working to improve your project’s documentation experience.
The result is called UnMarkDocs.
The problem with documentation
A year ago, I noticed there are two types of documentation: the one you keep coming back because you have no other choice and the one you prefer to StackOverflow. And it doesn’t always depend on the content.
Let’s see some examples:
Stripe’s documentation is one of the best out there, if not the best. Their docs are not only helpful but also beautiful and a pleasure to use. Definitely my go-to for Stripe problems.
On the other hand, the Bootstrap Datepicker docs are difficult to consume, begging me to exit the page despite how well-documented they might be. I may check them for the instructions but I’ll be ready to alt-tab to StackOverflow for any problems I encounter.
Okay, we aren’t being fair here. We’re comparing a VC funded multinational's documentation to an open source project’s one. Let’s try with another example.
Another of the best documentation pages I’ve found is Laravel's one, and not only because of the user-contributed content (the whole docs are open-source). It’s a pleasure to navigate this website.
What’s the difference? They care about their documentation experience.
But I’m working on an open source project! I can’t afford hiring a development team to develop a custom documentation CMS for my project!
Well, that’s the part where I can help you :)
So, what is UnMarkDocs?
Imagine an ideal world. You put your documentation on a GitHub repo, where your users can submit Pull requests to fix typos or improve your wording. Then you click a button and everything gets converted to a beautiful website you can access from
docs.yourproject.com. UnMarkDocs is that magic button on steroids.
Let’s return to reality. You create an UnMarkDocs account, link your GitHub docs repository and configure a custom domain. Boom, done!
It even auto-updates on every git push!
Remember how the title promised better markdown? Well, the markdown we use at UnMarkDocs isn’t the same you normally use. This doesn’t mean you have to re-learn Markdown. In fact, if you use your existing files you won’t notice the difference. But we’ve built some new things into Markdown to superpower your docs.
Our special Markdown flavour provides new syntax on top of the existing one to allow you to embed media like videos, gists or even an editable CodePen, add alerts, panels and other ways to get the user attention or adding a CTA (call to action) at the bottom of every page. And the best part is that everything is customizable from the markdown file itself.
Bringing the beauty in
Okay, so we have an auto-updating documentation users can collaborate on and we also have Markdown superpowers. But we’re missing one more thing to get to Laravel Docs level: Beautiful pages.
And, of course, UnMarkDocs can also help you with that.
Here you can see an example of how UnMarkDocs-powered pages look. The white part is rendered directly from your markdown file so you control exactly what it’s shown. The grey part? Yeah, you can customize that too from your dashboard. And if you’re not happy with how it looks, you can add your own styling via CSS.
One More Thing™
UnMarkDocs automatically generates navigation from your GitHub repository and anchors for the current page to ease navigation. It also includes a button linking to GitHub’s edit window for the current page, making community collaboration easier than ever. And if you don’t like any of this things, you can easily remove them.
Free for Open Source
As a way of thanking every person to contributes to open source, I’ve decided to offer a free plan that includes almost every UnMarkDocs feature. If you want to use custom domains or private repositories, you can use our coffee-priced Premium plan. Awesome, huh?
Bonus: Get 50% off your first month
The existing price isn’t expensive (
$5), but to thank you for reading until the end and to compensate you from the 30 seconds you’ll spend in the migration, use the coupon
AUTOMETALOGOLEX to get your first month of UnMarkDocs Premium for only
$2.5 . Less than a Starbucks coffee.
This is my first product launch and it’d be awesome if you could share UnMarkDocs with your friends, coworkers and cat. Also, if you want to talk about UnMarkDocs, other projects I’m working on or just about life in general, feel free to email me.