Developer Docs

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

1. Create a pull request
2. 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:

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

1. Create a new branch:

``bash git checkout -b docs/your-change ``

1. Make your changes
2. 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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: speakeasy-api
• Source: speakeasy-api/developer-docs
• License: MIT
• Homepage: https://www.speakeasy.com/docs

Install and usage instructions live in the source repository linked above.