What should I use for docs that include auth flows and examples?

For docs that include auth flows and examples, I’d usually recommend one of these:

Best general choice: Markdown + a docs site generator

Use Markdown for the content and something like:

• Docusaurus
• MkDocs
• Mintlify
• Nextra

Why:

• Easy to write and version-control
• Works well for code snippets and step-by-step auth flows
• Can be published as a polished docs site
• Good support for tabs, callouts, code highlighting, and navigation

If your docs are API-heavy: OpenAPI + Markdown

If auth is part of an API reference, use:

• OpenAPI/Swagger for endpoint definitions
• Markdown pages for guides and auth walkthroughs

This is a strong combo because:

• OpenAPI handles request/response schemas well
• Markdown handles explanations, flows, and examples better

For auth flows specifically, include:

• Sequence diagrams: Mermaid or PlantUML
• Code samples: cURL, JS, Python, etc.
• Copy-paste examples for tokens, headers, and redirects
• State diagrams / flowcharts for login, refresh, callback, token exchange

A practical recommendation

If you’re starting from scratch:

• Markdown + Docusaurus + Mermaid
• Add OpenAPI if you have endpoints to document

If you want, I can suggest a docs stack based on whether this is for:

1. internal engineering docs,
2. public developer docs, or
3. product/security auth documentation.