How to document a collection in Markdown in API Spector

A good collection explains itself. API Spector gives every collection, folder, and request a Documentation tab where you write notes in Markdown, and those notes travel with the collection into Git.

Open the Documentation tab

Select a collection or a folder in the sidebar, or open a request, and choose the Documentation tab (it is labelled Docs on a request). You get a text area with a Write and Preview toggle and a small formatting toolbar for headings, bold, lists, links, and code.

Write in plain Markdown

The editor is plain Markdown. Headings, bold and italic, inline and fenced code, ordered and unordered lists, blockquotes, links, and horizontal rules all render in Preview. Links are limited to http, https, and mailto, and the text is always escaped, so a preview never runs raw HTML from your notes.

## Auth
This collection uses a bearer token. Set {{token}} in your environment.

Run the **Login** request first; it stores the token for the others.

It lives in the collection

Documentation is saved on the item itself, in its description, which means it is part of the .spector file. Commit the file and the docs are versioned with the requests, reviewed in pull requests, and shared with everyone who opens the workspace. There is no separate docs store to keep in sync.

Document at the right level

Three levels cover most needs: the collection for an overview and auth notes, a folder for a group of related endpoints, and a request for the specifics of one call. Because each request carries its own docs, the notes stay next to the thing they describe.

Export when you need a page

When you want a standalone document to hand to someone, the toolbar's Docs button generates full API documentation from the collection as an HTML or Markdown file. That is separate from the in app tabs and is meant for sharing outside the app.

Why it helps

A request on its own rarely explains why it exists. Writing that down where the request lives, in Markdown you already know, and committing it with the collection, turns a set of calls into something a teammate can pick up without asking.