Skip to content

README.md

Latest commit

 

History

History
95 lines (65 loc) · 2.87 KB

README.md

File metadata and controls

95 lines (65 loc) · 2.87 KB

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.