Contributing to Speakeasy Documentation

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

📂 Repository Structure

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

✍️ How to Edit Content

1. Locate the File

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

2. Make Your Changes

• 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

3. Submit Your Changes

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

📝 Quick Style Guide

Writing Style

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

Code and Links

• 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

Formatting

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

🚀 Getting Started

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

🤝 Need Help?

• 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.