Should you use Markdoc for your SaaS docs?

Markdoc is a lightweight documentation tool that allows users to create and organise documentation using simple Markdown files. It converts the Markdown files into a stylish, easy-to-navigate website with a table of contents and search functionality.

Markdoc can be useful for SaaS companies in several ways. Firstly, it allows teams to create and maintain documentation in a simple and organised manner, without the need for a separate documentation platform. This can save time and resources for your company.

Additionally, Markdoc’s search functionality can make it easier for customers to find the information they need, improving the overall user experience. The sleek and professional design of the generated documentation website can also improve your company’s branding and credibility.

Markdoc is open-source, allowing companies to customize and extend its functionality to better suit their needs. This can also help to lower the cost of maintaining documentation.

Why should you use Markdoc? #

So Stripe’s docs are stunning. Any more upsides of using Markdoc?

Lightweight and easy to use #

Markdoc is a simple tool that allows users to create and organise documentation using Markdown files, making it easy to get started and use as you are most likely already familiar with markdown using your static site generator.

Customisable and extendable #

Markdoc is open-source, allowing you to customise and extend its functionality to better suit their needs.

Cost-effective #

Being open-source, makes it a cost-effective solution.

Professional design #

The generated documentation website is sleek and professional, which can improve your company’s branding and credibility.

Why should you not use Markdoc? #

All promising! Are there any downsides to using Markdoc?

Limited functionality #

It is a simple tool and may not have as many features as other more comprehensive documentation tools.

Limited integration #

Markdoc may have limited integration with other tools, which can make it difficult to integrate with other systems used by your company.

What are some (paid) alternative tools? #

There are a plethora of tools available that allow you to create beautiful documentation site, with little effort. The biggest downside is, like discussed in this article about web builders, your docs will live on a subdomain. Leaving you without the extra SEO juice. That said these are some of the paid, SaaS tools available to you.

ReadMe is a documentation platform that allows teams to create, manage, and publish documentation, as well as track analytics and gather feedback.
Gitbook is a platform that allows teams to create and collaborate on documentation using Markdown, as well as integrate with other tools like Jira and Slack.
HelpDocs is a documentation platform that allows teams to create and organise documentation, as well as customise the design and branding of the documentation website.
Notion is a productivity and organisation tool that can be used to create and organise documentation, although it is not a specialised documentation tool.

Getting started with Markdoc #

The process of setting up Markdoc is relatively straightforward and well-documented, and you should be able to get started with it quickly. Check out the docs for more info.

Example of Markdoc in the wild #

Being built by Stripe, the Stripe docs are the most obvious example that use Markdoc. Other examples of companies that use it to create and maintain their documentation.

Do you use Markdoc for you documentation. Let us know and get listed here.

General static site generator or Markdoc? #

Markdoc is a simple and lightweight tool that is specifically designed for creating and organizing documentation, while Static Site Generators (SSG) like Jekyll, Astro and 11ty are more general tools that can be used to create a wide variety of websites, including documentation websites, but require more technical knowledge and resources.

Specifically designed for documentation #

Markdoc is specifically designed for creating and organising documentation, while SSG are more general tools that can be used to create a wide variety of websites (including documentation websites).

Functionality #

Markdoc provides a simple and easy-to-use interface for creating documentation using Markdown files, as well as generating a stylish, easy-to-navigate website with a table of contents and many features to build highly customisable documentation. SSG are more flexible and provide more functionality, such as template engines, asset management, and more.

Customization #

Markdoc provides a limited amount of customisation options, and you can only customise the design and layout of the generated website. In contrast, SSG provide a wide range of customisation options and can be extended with plugins and add-ons.

Integration #

Markdoc may have limited integration with other tools, while SSG can be integrated with a wide range of tools and services, such as a CMS, analytics tools, and more.

If you should use Markdoc (within your static site generator), use your static site generator as-is or go with any of the SaaS tools available depends on multiple things. In general I advice against using multiple, separate tools for your (marketing) content. Having all your content (created and maintained with Spinal) in your static site generator makes it easy to search, reference and store on your main domain (big plus!).

Note: at Spinal, we’ve designed, built and maintain a beautiful docs theme for various static site generators.

Written by July Forand

Published: 26 January 2023 (updated: 9 February 2023)