Carte

Carte is a Jekyll-based boilerplate for building static API documentation websites, designed for teams that want simple, server-free docs.

What is Carte?

Carte is a simple Jekyll-based documentation website for APIs, built as a boilerplate for creating your own documentation. It takes API call descriptions written as Markdown posts in the _posts folder and renders them into a navigable static site. Each post's YAML header defines the title, URL path, and HTTP method, while the body holds the request/response description. Carte was inspired by Swagger and I/O docs, but focuses on static documentation without an interactive API explorer.

Key Features

• Jekyll-based structure — API calls are added as posts with YAML front matter, using the same workflow as a Jekyll blog; dates in filenames control the order of calls.
• HTTP method labels — The type field in each post's header can be set to PUT, GET, POST, DELETE, or left empty for documentation sections that are not actual API calls.
• Path parameters support — The path field defines the endpoint URL, including placeholders like /stuff/:id, so parameterized routes are documented naturally.
• Grouping via categories — Adding a category to a post's YAML header groups related methods together in the navigation sidebar.
• Customizable UI — The default design lives in css/style.css and a couple of jQuery scripts in /_layouts/default.html, making it straightforward to restyle.
• No server required — Documentation compiles to static files, eliminating the need to run a dedicated documentation server.
• JSON-oriented — Built for APIs that send JSON objects rather than a long series of query parameters.

Who is it for?

• API developers — who want to document endpoints quickly without learning a heavyweight documentation platform.
• Small teams — with limited infrastructure who prefer a static site they can host on GitHub Pages or any web server.
• Teams wary of interactive explorers — who don't want users accidentally triggering destructive POST or DELETE calls while trying out the API.

What can you do with Carte?

• Publish internal API references: Document endpoints with curl-style examples and response schemas for your engineering team.
• Ship public developer docs: Deploy the generated HTML to a static host for external developers.
• Prototype documentation structure: Use Carte's post-per-call model to design the information architecture before writing content.

How does Carte work?

1. Clone the repository and install Jekyll on your local machine.
2. Run jekyll serve --watch from the repository root and open http://localhost:4000 to preview.
3. Add a new Markdown file in _posts with a YAML header containing title, path, and type.
4. Write the request and response details in the post body.
5. Optionally add a category to group calls; the navigation updates automatically.

Carte's real value is its structured way of describing APIs, and the repository has 733 stars on GitHub as an open-source project.