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.