Key takeaway: That three-column API reference layout, prose on the left and code samples pinned right, is what Slate is for, and it still reads correctly because everyone copied it. Choose it for an existing site, or for a hand-written reference you want online quickly. Anything driven by an OpenAPI specification belongs elsewhere.
Quick facts
- LanguageRuby
- CategoryRuby
- LicenseApache-2.0
- Created2014
- GitHub stars36.7k
- Statusmature
Templating: Middleman Markdown
What it is
Slate generates a single-page API documentation site with the three-column layout popularised by Stripe's API docs. Built on Middleman. Mature, popular for older API doc projects.
Best for
- Single-page API documentation in the Stripe style
- Existing Slate sites with no reason to migrate
When not to pick it
For new projects pick Mintlify, Starlight, or a modern OpenAPI-aware tool. The single-page API doc shape is no longer the default.
My take
Slate had its moment. Modern alternatives are easier to live with. Migrate when you replatform.
The layout that defined API documentation
Slate produces a single scrolling page: a fixed table of contents down the left, prose in the middle, and a dark code column on the right showing the current example in whichever language the reader picked. It is a good design, which is why an entire generation of API documentation looks like this. Everything is Markdown in one directory, so a small API can be documented properly by one engineer in a day, and the output is static HTML with no runtime, deployable anywhere including GitHub Pages. The tabbed language selector is the detail people miss most when they move away: you write curl, Python, and JavaScript samples side by side, and the page keeps the reader's chosen language consistent as they scroll through every endpoint.
The Ruby toolchain and the OpenAPI gap
Two things date Slate. First, it is a Middleman site, which puts a Ruby and Bundler toolchain into CI for a project that otherwise has nothing to do with Ruby, and drift on that toolchain is the usual reason an old Slate build suddenly stops working. Second, and more important, it has no concept of an OpenAPI specification. Your documentation is hand-written Markdown that will silently disagree with your API the first time an endpoint changes, and keeping the two aligned is a discipline problem you have to solve with process. Modern documentation tools generate reference pages from the spec so that drift is structurally impossible. If you have a spec, Mintlify or Starlight with an OpenAPI integration is a better place to put the effort.
Frequently asked questions
Is Slate still maintained?
It is mature rather than actively developed, with changes arriving slowly. Existing sites keep building, and the design has aged well because it was widely imitated. For a new documentation project the slow cadence plus the Ruby toolchain requirement is a reason to look at Starlight, Mintlify, or Docusaurus, all of which have more momentum behind them.
Does Slate support OpenAPI?
Not natively. Slate expects hand-written Markdown, so there is no live link between your specification and your published reference. Community converters can turn a spec into Slate-flavoured Markdown as a one-time step, but that output then needs maintaining by hand. If your API has a spec you intend to keep current, choose a tool that renders from it directly.
Slate or Mintlify?
Slate if you want free, self-hosted, static output with no vendor involved and you are documenting a small, stable API by hand. Mintlify if you want polish, OpenAPI-driven reference pages, search, and analytics without engineering effort, and you accept a hosted product whose cost scales. The trade is ownership and price against maintenance burden and freshness.
Links
Similar tools you should also consider
If Slate is your pick, the next conversation is short
The 30-min call is where your project gets a real architecture, an SEO transport plan, and a price range you can take to your team. Describe your site, your timeline, your existing content. I tell you whether Slate is genuinely the right call for you, and what the build actually looks like.