DEV Community

Cover image for UnMarkDocs: Better Markdown for your documentation
Miguel Piedrafita
Miguel Piedrafita

Posted on • Originally published at blog.miguelpiedrafita.com on

UnMarkDocs: Better Markdown for your documentation

šŸ‘‹ 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:

UnMarkDocs: Better Markdown for your documentation
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.

UnMarkDocs: Better Markdown for your documentation
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.

UnMarkDocs: Better Markdown for your documentation
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.

UnMarkDocs: Better Markdown for your documentation
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.


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.


Closing

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.

Top comments (0)