{"id":34521341,"url":"https://github.com/speakeasy-api/docs-md","last_synced_at":"2026-06-08T07:02:43.663Z","repository":{"id":323011630,"uuid":"983004659","full_name":"speakeasy-api/docs-md","owner":"speakeasy-api","description":"OpenAPI =\u003e Docs ⚡️","archived":false,"fork":false,"pushed_at":"2025-12-24T00:43:26.000Z","size":361916,"stargazers_count":7,"open_issues_count":3,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-05-25T05:34:25.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speakeasy-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-13T18:21:23.000Z","updated_at":"2026-01-06T14:12:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/speakeasy-api/docs-md","commit_stats":null,"previous_names":["speakeasy-api/docs-md"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/speakeasy-api/docs-md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fdocs-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fdocs-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fdocs-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fdocs-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speakeasy-api","download_url":"https://codeload.github.com/speakeasy-api/docs-md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fdocs-md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34051772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T04:57:49.605Z","updated_at":"2026-06-08T07:02:43.658Z","avatar_url":"https://github.com/speakeasy-api.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DocsMD\n\n\u003e **⚠️ This project is under development**\n\u003e\n\u003e It is provided as-is under the Elastic License 2.0 and may be extended or inherited according to the license constraints\n\u003e\n## What is DocsMD?\n\nDocsMD is a powerful documentation compiler that transforms OpenAPI specifications into interactive API documentation for popular documentation frameworks. It bridges the gap between your API specification and production-ready documentation sites with minimal configuration.\n\n**Key Features:**\n\n- **Framework Support**: Generate documentation for Docusaurus, Nextra, or create custom renderers for any framework\n- **Interactive Code Samples**: Automatically generate code examples in multiple languages (TypeScript, Python, cURL)\n- **Try It Now**: Enable browser-based API testing with live code execution for TypeScript and Python SDKs\n- **Rich Component Library**: Pre-built React components for displaying API operations, schemas, parameters, and responses\n- **Type-Safe**: Full TypeScript support with generated type definitions\n- **Customizable**: Override default components and styling to match your brand\n- **MDX \u0026 Markdown**: Flexible rendering to MDX for React-based frameworks or pure Markdown for LLMs\n\n## Why DocsMD?\n\nTraditional API documentation tools often require significant manual effort to maintain or produce generic, static output. DocsMD solves this by:\n\n1. **Automation**: Generate comprehensive documentation directly from your OpenAPI spec\n2. **Consistency**: Ensure your documentation always matches your API specification\n3. **Developer Experience**: Provide interactive code samples and live API testing\n4. **Flexibility**: Works with modern documentation frameworks or custom solutions\n5. **Extensibility**: Override and customize every aspect of the generated documentation\n\n## Monorepo Structure\n\nDocsMD is organized as a monorepo with four main packages:\n\n### 📦 `@speakeasy-api/docs-md` (Compiler)\n\nThe core compiler package that orchestrates the documentation generation process.\n\n**Purpose**: Parses OpenAPI specifications and generates framework-specific documentation files.\n\n**Key Exports**:\n- CLI tool (`docs-md`) for generating documentation\n- `generatePages()` - Programmatic API for generation\n- `FrameworkConfig` - Type definitions for custom renderers\n- `Settings` - Configuration schema\n\n**Location**: `packages/compiler/`\n\n### ⚛️ `@speakeasy-api/docs-md-react` (React Components)\n\nReact component library used in the generated MDX documentation.\n\n**Purpose**: Provides rich, interactive UI components for displaying API documentation.\n\n**Key Components**:\n- `Operation` - Displays API operations with method, path, and details\n- `CodeSample` - Syntax-highlighted code examples\n- `TryItNow` - Interactive API testing interface\n- `ExpandableSection` - Collapsible sections for schemas and parameters\n- `ResponseTabbedSection` - Multi-response display with tabs\n- `Pill` - Badges for methods, types, and status codes\n\n**Location**: `packages/react/`\n\n### 🔧 `@speakeasy-api/docs-md-shared` (Shared)\n\nShared utilities, types, and runtime code used across packages.\n\n**Purpose**: Common code and type definitions to avoid duplication.\n\n**Key Exports**:\n- TypeScript and Python runtime for Try It Now feature\n- cURL parser and runtime\n- Type definitions for chunks, logging, and configuration\n- ESLint and Prettier configurations\n\n**Location**: `packages/shared/`\n\n## Compiler Architecture\n\n### Renderer Types\n\nDocsMD supports multiple renderer types to accommodate different output formats:\n\n#### 1. **MDX Renderer** (`rendererType: \"mdx\"`)\n\nGenerates MDX (Markdown + JSX) files for React-based documentation frameworks.\n\n**Use Cases**:\n- Docusaurus sites\n- Nextra (Next.js) documentation\n- Custom React-based documentation platforms\n\n**Features**:\n- Embeds React components directly in markdown\n- Supports interactive features like Try It Now\n- Type-safe component props\n- CSS styling integration\n\n**Configuration**:\n```typescript\n{\n  rendererType: \"mdx\",\n  componentPackageName: \"@speakeasy-api/docs-md-react\",\n  stringAttributeEscapeStyle: \"html\" | \"react-value\"\n}\n```\n\n#### 2. **Markdown Renderer** (`rendererType: \"markdown\"`)\n\nGenerates pure Markdown output without embedded components.\n\n**Use Cases**:\n- LLM training data\n- Documentation that needs to be portable\n- Static site generators without React support\n- Plain text documentation needs\n\n**Features**:\n- Clean, readable Markdown\n- No framework dependencies\n- Maximum portability\n- SEO-friendly content\n\n### Core Rendering Process\n\nThe compiler follows this high-level flow:\n\n1. **Parse OpenAPI Spec**: Load and validate the OpenAPI specification\n2. **Generate Data Structures**: Convert OpenAPI into internal \"chunks\" (operations, schemas, tags, etc.)\n3. **Prepare Code Samples**: Generate code examples for configured languages\n4. **Render Pages**: Use the appropriate renderer (MDX or Markdown) to create documentation files\n5. **Post-Process**: Apply framework-specific transformations and optimizations\n6. **Write Output**: Save generated files to the configured output directory\n\n### Page Generation\n\nPages are generated for:\n\n- **Tags**: Groups of related operations\n- **Operations**: Individual API endpoints\n- **Schemas**: Data models and object definitions\n- **Global Security**: Authentication/authorization documentation\n- **About**: API overview and information\n\n### Extensibility\n\nCreate custom renderers by implementing the `FrameworkConfig` interface:\n\n```typescript\nimport type { FrameworkConfig } from '@speakeasy-api/docs-md';\n\nconst customConfig: FrameworkConfig = {\n  rendererType: \"mdx\",\n  componentPackageName: \"my-custom-components\",\n  stringAttributeEscapeStyle: \"react-value\",\n  buildPagePath: (slug, options) =\u003e {\n    // Custom path generation logic\n  },\n  buildPagePreamble: (frontMatter) =\u003e {\n    // Custom front matter generation\n  },\n  postProcess: (pageMetadata) =\u003e {\n    // Custom post-processing\n  }\n};\n```\n\n## Usage Guide\n\n### Installation\n\nInstall the DocsMD CLI as a dev dependency in your documentation project:\n\n```bash\n# Using npm\nnpm install --save-dev @speakeasy-api/docs-md\n\n# Using yarn\nyarn add -D @speakeasy-api/docs-md\n\n# Using pnpm\npnpm add -D @speakeasy-api/docs-md\n```\n\n### Basic Configuration\n\nCreate a `speakeasy.config.mjs` (or `.js`, `.ts`, etc.) file in your project root:\n\n```javascript\nexport default {\n  // Path to your OpenAPI specification\n  spec: \"./openapi.yaml\",\n\n  output: {\n    // Where to generate documentation files\n    pageOutDir: \"./docs/api\",\n\n    // Framework: \"docusaurus\", \"nextra\", or custom config\n    framework: \"docusaurus\",\n  },\n};\n```\n\n### Running the Compiler\n\n```bash\n# Using the CLI directly\nnpx docs-md\n\n# With options\nnpx docs-md --clean --verbose\n\n# Using package.json scripts (recommended)\nnpm run build-api-docs\n```\n\nAdd to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"build-api-docs\": \"docs-md --clean\"\n  }\n}\n```\n\n### CLI Options\n\n```\nUsage: docs-md [options]\n\nOptions:\n  --help, -h     Show this help message\n  --config, -c   Path to config file\n  --spec, -s     Path to OpenAPI spec file\n  --clean, -C    Clean the output directories before generating\n  --verbose, -v  Show debug output\n```\n\n### Advanced Configuration\n\n#### Code Samples with Multiple Languages\n\n```javascript\nexport default {\n  spec: \"./openapi.yaml\",\n  output: {\n    pageOutDir: \"./docs/api\",\n    framework: \"docusaurus\",\n  },\n  codeSamples: [\n    {\n      language: \"curl\",\n      tryItNow: true, // Enable Try It Now for cURL\n    },\n    {\n      language: \"typescript\",\n      sdkTarballPath: \"./sdks/typescript-sdk.tar.gz\",\n      tryItNow: {\n        outDir: \"./public/try-it-now/ts\",\n        urlPrefix: \"/try-it-now/ts\",\n      },\n    },\n    {\n      language: \"python\",\n      sdkFolder: \"../python-sdk\",\n      tryItNow: {\n        outDir: \"./public/try-it-now/python\",\n        urlPrefix: \"/try-it-now/python\",\n      },\n    },\n  ],\n};\n```\n\n#### Custom Display Options\n\n```javascript\nexport default {\n  spec: \"./openapi.yaml\",\n  output: {\n    pageOutDir: \"./docs/api\",\n    framework: \"nextra\",\n    embedOutDir: \"./docs/embeds\", // For nested schemas\n  },\n  display: {\n    maxNestingLevel: 3, // Maximum depth for inline schemas\n  },\n};\n```\n\n#### Using Spec Data Instead of File\n\n```javascript\nimport { readFileSync } from 'fs';\n\nexport default {\n  specData: readFileSync('./openapi.yaml', 'utf-8'),\n  output: {\n    pageOutDir: \"./docs/api\",\n    framework: \"docusaurus\",\n  },\n};\n```\n\n### Overriding React Components\n\nDocsMD components can be customized, but the approach differs from typical React applications because the generated MDX files import components directly by name.\n\n#### Understanding Component Imports\n\nGenerated MDX files include imports like this:\n\n```typescript\nimport {\n  Operation,\n  CodeSample,\n  TryItNow,\n  ExpandableSection\n} from \"@speakeasy-api/docs-md-react\";\n```\n\nBecause components are imported directly by name in each generated file, standard MDX provider overrides **will not work**.\n\nCreate your own component package that re-exports modified versions:\n\n**Step 1**: Create `my-custom-docs-components` package:\n\n```typescript\n// my-custom-docs-components/src/index.ts\n\n// Re-export all default components\nexport * from '@speakeasy-api/docs-md-react';\n\n// Override specific components\nexport { CustomCodeSample as CodeSample } from './CustomCodeSample';\nexport { CustomOperation as Operation } from './CustomOperation';\n```\n\n**Step 2**: Use custom package in config:\n\n```javascript\n// speakeasy.config.mjs\nexport default {\n  spec: \"./openapi.yaml\",\n  output: {\n    pageOutDir: \"./docs/api\",\n    framework: {\n      rendererType: \"mdx\",\n      componentPackageName: \"my-custom-docs-components\", // Your package\n      stringAttributeEscapeStyle: \"react-value\",\n      buildPagePath: (slug) =\u003e `${slug}.mdx`,\n      buildPagePreamble: (frontMatter) =\u003e `---\\n${JSON.stringify(frontMatter)}\\n---`,\n    },\n  },\n};\n```\n\n#### Styling Customization\n\nDocsMD uses CSS custom properties (variables) for theming:\n\n```css\n/* custom.css */\n:root {\n  /* Override Speakeasy CSS variables */\n  --speakeasy-border-color: #e0e0e0;\n  --speakeasy-code-background-color: #1e1e1e;\n  --speakeasy-anchor-color: #0066cc;\n  --speakeasy-pill-primary-background-color: #0066cc;\n\n  /* Add your custom variables */\n  --my-custom-spacing: 1.5rem;\n}\n```\n\nFor a complete list of available CSS variables, see:\n- `packages/react/src/docusaurus.css`\n- `packages/react/src/nextra.css`\n\n#### Component Architecture\n\nDocsMD components follow a \"slots\" pattern for flexibility:\n\n```tsx\n\u003cResponseTabbedSection\u003e\n  \u003cSectionTitle slot=\"title\"\u003e\n    ### Responses\n  \u003c/SectionTitle\u003e\n\n  \u003cSectionTab slot=\"tab\" id=\"200\"\u003e\n    200 OK\n  \u003c/SectionTab\u003e\n\n  \u003cSectionContent slot=\"section\" id=\"200\"\u003e\n    Success response content\n  \u003c/SectionContent\u003e\n\u003c/ResponseTabbedSection\u003e\n```\n\nThis allows content to be authored in Markdown while maintaining structure.\n\n## License\n\nThis project is licensed under the **Elastic License 2.0**. See the [LICENSE](./LICENSE) file for full terms.\n\nThis project is provided as-is without warranty or support. For historical documentation or questions, please refer to the codebase and existing documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fdocs-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeakeasy-api%2Fdocs-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fdocs-md/lists"}