Welcome to the Speakeasy documentation repository! This guide will help you contribute to our open-source documentation.

The documentation is organized into several content hubs:

• api-design/ - API design guidelines and best practices
• docs/ - Core product documentation
• guides/ - Step-by-step product guides
• mcp/ - MCP hub
• openapi/ - OpenAPI hub
• public/ - Shared static assets (images, downloads, etc.) served on the site

The documentation files in this repository directly map to the URLs on our website. To find the file you want to edit:

1. Take the URL path after speakeasy.com/
2. Add .mdx to the end
3. That's your file path in the repository

For example:

• Website URL: https://www.speakeasy.com/docs/prep-openapi/linting
  • File path: docs/prep-openapi/linting.mdx

• Use MDX (.mdx) when you need React components, or Markdown (.md) for simple content
• Follow our quick style guide below
• Include proper meta descriptions for SEO
• Optimize images using Next.js Image component
• Store any public/static assets in public/
• Update _meta.global.tsx to adjust sidebar ordering where needed

1. Create a new branch for your changes
2. Commit with a descriptive message following Conventional Commits
   • Example: chore: update authentication guide
3. Create a pull request
4. Once approved, your changes will be merged

• Use clear, concise language
• Write in active voice
• Keep explanations brief and direct
• Use American English

• Use code blocks for code snippets
• Add language specification to code blocks
• Use relative URLs: [link](/docs/create-client-sdks)
• Place code references in backticks

• Use sentence case for headings
• Use proper heading hierarchy
• Include code examples where relevant
• Add proper meta descriptions for SEO

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/developer-docs.git

3. Create a new branch:

   git checkout -b docs/your-change

4. Make your changes

5. Submit a pull request

• Open an issue for general questions
• Join our Slack community for real-time help
• Check existing issues and pull requests for similar questions

Thank you for contributing to our documentation! Your help makes our documentation better for everyone.