Why You Should Use Markdown for Your API Documentation

Markdown is a simple markup language that's been gaining popularity for use with API documentation. Several tools are available that can convert Markdown into HTML so that it can be displayed in browsers. These include Swagger, RAML, ReadMe.io and Apiary.io and we’ll look at each later. So, what is Markdown, and why does it work so well for API documentation?

The key word is simple. As a markup language, Markdown hearkens back to the very early days of HTML and provides features for bold, italic, headers, links, images, code blocks, and a small number of other features. It contains no style information. Compared to HTML, it has a very clean look, making it much more human-readable than HTML. Consider the following HTML:

<h2>Notes</h2>

The <code>GET users</code> request can be used with the <em>group</em> query parameter to filter to a group. See the <a href="../users/">users</a> resource page.

Now, the same in Markdown:

## Notes

The `GET users` request can be used with the *group* query parameter to filter to a group. See the [users](../users/) resource page.

You can see how much more readable Markdown is. If Markdown doesn't have what you need, you can always insert HTML just for the parts it doesn't cover.

Why does it work well for API documentation?

API documentation should not have a fancy look to it. Its look should be very clean because readability is the most important aspect of the look-and-feel. This means that the fact that Markdown does not allow style information is not a big issue.

Also, compared to other technical writers, API documentation writers are usually very comfortable working directly in a markup language without a WYSIWYG tool. Markdown is easy to work with in a text editor, especially compared to HTML.

Markdown can be used for both overview and reference material. Markdown also has advantages over tools that generate reference documentation from the text in code or structured data,like JSON or XML. Examples of these tools include I/O Docs, XSDDoc and oXygen. First, it's very flexible, so it doesn't have some of the limitations of automated systems that can only handle plain text. It also offers the ability to include links, images, rich text, and multiple paragraphs, and it will all look fine.

Markdown flavors

There's more than one kind of Markdown. These variations are called Markdown "flavors". It's important that you choose a flavor that supports tables, since tables are often used in API reference documentation.  (The original flavor of Markdown does not support tables. GitHub-Flavored Markdown is a common flavor that supports tables.)

If your Markdown flavor does not support tables, then you can still create them with HTML, but HTML tables require a lot of tags that make it hard to read the content.  Here is a small table in HTML:

<table>
  <tr>
    <th>Error code</th>
    <th>Description</th>
  <tr>
    <td>1</td>
    <td>The start date is after the end date.</td>
  </tr>
  <tr>
    <td>2</td>
    <td>The start date is before the current date.</td>
  </tr>
</table>

Now the same in GitHub-Flavored Markdown:

Error Code | Description
---------- | -------------
1 | The start date is after end date.
2 | The start date is before the current date.

Markdown Tools

Several tools are available for creating documentation in Markdown.

GitHub

If you use GitHub as a repository, you can add Markdown files in two ways:
•   For any directory in GitHub, create a Markdown file called README.md. GitHub automatically converts this file to HTML and displays it underneath the listing of files in the directory. For an example, see the Getty Images Connect API.
•   In addition, you can add any documentation as Markdown with a .md suffix and when someone clicks on it, GitHub will display the HTML for the Markdown file. See the Getty Images Connect OAuth page as an example.

ReadMe.io, Apiary.io, Swagger, and RAML tools

There are now several tools available that generate API documentation from data, and many of them incorporate Markdown as a way to allow more complex documentation of APIs than simply text. In addition, these tools allow users to try out an API from within the documentation.

ReadMe.io is a commercial platform for REST API documentation with several options to customize it. They provide an editor that works for both conceptual and reference pages, and you can use their GUI editor buttons or Markdown, or a combination of both. They also allow you to define your API in GitHub which they can read and populate your documentation with the basic information, so that all you need to do is to add the documentation.

Apiary.io is another commercial platform. It uses a format called API Blueprint that also incorporates Markdown. Apiary.io creates reference documentation that also can be customized.

The latest versions of Swagger allow you to use a combination of YAML and Markdown to create your reference documentation. Swagger is open source, which means that if you are willing to spend the time with it, you can make it look exactly how you like it.

Another format to describe REST APIs is called RAML, for RESTful API Modeling Language. RAML also has the ability to incorporate Markdown. There are several tools available to convert RAML into documentation: API Designer, RAML to HTML, gulp-RAML2HTML, and RAML2Wiki.

WordPress

WordPress is an extremely popular content management system, and there is now a WordPress Markdown Plug-in that lets you write content in Markdown. This gives you all of the advantages of the WordPress content management system, such as themes, plug-ins, version control, etc, but makes it very simple to create API documentation. There are disadvantages, however. For example, if you want to do a global search-and-replace because the URL of a resource has changed, you do not have direct access to the Markdown files. However, there are plug-ins available that can help you with this.

Markdown to HTML Tools

You may find that none of the available API documentation tools meet your needs. There are several tools that convert Markdown to HTML, making it easier to create your own documentation system. Here are a few:
•   Jekyll
•   Kirby
•   MarsEdit

 
Peter Gruenbaum Peter Gruenbaum has worked as an API writer to describe APIs for eCommerce, traffic prediction, electric utilities, mobile devices, tractors, and cat humor sites, just to name a few. His company, SDK Bridge, specializes in making APIs more engaging for developers by writing API documentation, sample code, and wrapper SDKs.

Comments

Comments(1)

JamesCurran

I'd long been an advocate of using HTML for documentation, over the two leading candidates --- flat, hard-formatted, 80-column limited text; and MSWord for those that like formattings.

HTML combines the best of both of them, easily written in a text editor (nd therefore easily version in source control) and easily displayed in full-formatting.

Markdown seems to take that a step further, particularly in the first reason cited above --- but, turns out it fails in the second --- there really is not *simple* way to display in formatted.   Alternates are either a side-by-side editor, or the two step process of MD ->HTML -> display.

However, I don't see this as a fault of Markdown --- it a problem with our operating systems.  We need to campaign to make MarkDown viewers on computers as ubiquitous as HTML viewers (i.e. browsers) or PDF viewers or even MSWord viewers.