Write your API docs in Markdown and get them converted into pretty HTML🎨
Pastel is a tool for generating pretty API documentation from Markdown. Write your docs in Markdown and let Pastel convert it to a HTML page, complete with:
- mobile responsiveness
- syntax highlighting for code examples in multiple languages
- a table of contents for easy navigation
- search functionality
- automatic "Last updated" tag, so your users know how fresh the docs are
- a logo, if you like
- custom HTML and CSS helpers for when you want to apply special styles
Want to see it in action? Here's what the output looks like.
composer require --dev knuckleswtf/pastel
With Pastel, you write your docs in Markdown, and you get complete HTML/CSS?JS output. Here's what you need to know:
Start off with a single Markdown file. There are two parts:
Your Markdown file should contain your docs, written as you like. There's no set format, but you can start with an introduction, talk about authentication and any general details, then describe each endpoint in its own section. Write example requests and responses using code blocks, use tables or paragraphs to describe request and response parameters.
Pastel uses the same Markdown syntax as Slate. See How to Edit Slate Markdown files
The front matter is a YAML section in your Markdown file that comes before the actual content. It's separated from the main content by a line before and after it containing only "---" (see stubs/index.md).
--- # This section is the front matter title: API Docs --- This section is the content.
The front matter provides "meta" information about a Markdown document's contents (in this case, the API doc). You can use it to customise how your documentation will look like. Here are the values Pastel supports:
title: The page title. This is used as the value of
<title>, so it's only shown on the browser window.
language_tabs: Array of languages to switch between in the code samples. Please list them in the same order your code blocks are. Supported languages for highlighting:
ruby. You can use other languages too, but you won't get syntax hghlighting.
toc_footers: Array of items to add below your table of contents. See Slate's docs.
logo: If you'd like to use a logo on the sidebar, set this to the path to the logo image file. Must be either a URL or a path relative to the docs destination from a browser. The image will have to fit in a 230px width box (the sidebar), so make sure it scales nicely.
includes: This is where you can append more files to the main Markdown file you're using. Each entry in this array is the path to a Markdown file relative to the main file. So, if your folder structure is like this:
source/ |- index.md |- includes/ |- errors.md |- appendix.md
you can append the other files to
index.md by using
includes: - ./includes/appendix.md - ./includes/errors.md
You can also use
* as a wildcard. In this case, files matching the pattern will be included in alphabetical order.
includes: - ./includes/*.md
last_updated: The date on which the docs were last updated. Helpful so your users know if they're looking at something stale. Leave this empty and it will automatically be set to the most recent time you edited your Markdown files (main or includes). If you want to set this manually, you can write whatever you want here. Pastel will render it as is.
Most of these sections can be disabled in the generated documentation by omitting them from the front matter.
./vendor/bin/pastel generate docs_source/index.md docs
This will generate the HTML output from the file
docs_source/index.md with vendor/knuckleswtf/pastel/stubs/index.md to use the sample Markdown docs included with this package.
You can also call Pastel from PHP. This is especially useful if you're building a tool on top of it (see Integrations below. Here's how you'd use it:
$pastel = new Knuckles\Pastel\Pastel(); $pastel->generate("docs_source/index.md", "docs");
You can easily add badges by using the
badge CSS class, along with one of the
<small class="badge badge-darkred">REQUIRES AUTHENTICATION</small> <small class="badge badge-green">GET</small>
You can help your lower-level headings stand out by using the
<h4 class="fancy-heading-panel"><b>Body Parameters</b></h4>
You can add little highlighted warnings and notes using the
<aside> tag and either of the classes "notice", "warning", or "success".
- Scribe: Generate documentation for your Laravel API from your codebase.
- Custom favicon support
- Customizable output templates