Markdown to API Doc Guide

API documentation usually begins as rough Markdown in a pull request, a product note, or a model-generated draft. That is fine for capture, but rough notes are hard to reuse unless headings, examples, and request sections follow a repeatable shape.

1. Give each endpoint a stable top-level section

Start with the action name or route, then use predictable subheadings like Request body, Query parameters, Headers, and Response. Readers skim docs by structure before they read details.

2. Keep examples close to the section they explain

Putting JSON examples immediately under the request or response heading shortens the path from concept to implementation. It also makes conversion into HTML or an internal portal more reliable because each block already has a clear role.

3. Preview the result before publishing

Converting Markdown to HTML is not just about cosmetics. Previewing catches malformed lists, unclosed code fences, and heading drift that can break your generated table of contents.