Written on November 5, 2013 at 1:41 pm, by Robert Lord
If you’re a developer, you are probably aware of the pains of writing API documentation. APIs are annoying to document. Not only are they very long and painstakingly detailed, but making such a large technical document easy to read and navigate is not a trivial task.
Today, we’re open-sourcing Slate, a smart, easy API documentation template that you are free to use to document your own website’s API.
Getting Started with Slate
Right out of the box, Slate has an automatically generated, smoothly animated table of contents on the far left of the page. As you scroll, it displays your current position in the document:
Slate also has a section for code samples (complete with syntax highlighting) on the right side of the page. If your API has bindings in multiple programming languages, you can even put in tabs so that readers can easily switch between the languages:
Near-Painless Programming & Publishing
Publishing with Slate is also a breeze. Just run a single command — rake publish — and Slate will automatically publish your documentation to Github pages. If you’re not a Github pages type, you can always use rake build, and Slate will give you a bunch of static HTML to serve from wherever you’d like.
The best part is that all these features are super easy to use. When your write a document in Slate, you’re just writing Markdown. The endpoint descriptions are all Markdown. The table of contents is automatically generated from your Markdown headers. Even the code samples are just Markdown code blocks.
We hope that by open sourcing Slate, we can make it a little easier for you to write nice API documentation for your web service. Visit the Slate source on Github to get started today! And keep an eye out for the release of our API v2, coming soon to a TripIt developer blog near you.