UnMarkDocs: Better Markdown for your documentation

June 19, 20184 min read

👋 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:

The Stripe Docs

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.

Bootstrap Datepicker Documentation

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.

The Laravel Documentation

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!

Better Markdown

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.

Example UnMarkDocs-powered documentation

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.


Closing

This is my first product launch and it'd be awesome if you could share UnMarkDocs with your friends, coworkers and pets. Also, if you want me to keep you on the loop, you can subscribe to my newsletter to get project updates in your inbox.

Enjoyed the article? Consider sharing it on Twitter so others can enjoy it too :)

Share on Twitter

Receive project updates, article drafts & thoughts on your inbox every saturday.

Subscribe