Docusaurus Bruno API Documentation Generator Plugin

This Docusaurus plugin automatically generates comprehensive API documentation from Bruno collection files (.bru files). It parses Bruno's proprietary file format and generates interactive API documentation that integrates seamlessly with your Docusaurus documentation site.

Features

• Automatic Documentation Generation: Parse .bru files and generate Markdown documentation
• HTTP Method Badges: Color-coded badges for different HTTP methods
• MDX v3 Compatible: Generated markdown is compatible with MDX v3 requirements
• Authentication Support: Include authentication requirements and details
• Docusaurus Integration: Seamless integration with Docusaurus navigation and search
• File Watching: Automatic regeneration during development
• Version Flattening: Option to show only the highest version of each endpoint
• Folder-as-Page Mode: Group all requests in a folder into a single page
• Customizable: Configurable output paths, exclusions, and features

Installation

Install the plugin from npm:

npm install --save-dev docusaurus-plugin-bruno

Configuration

Add the plugin to your docusaurus.config.ts:

import type { Config } from '@docusaurus/types';

const config: Config = {
  // ... other config
  plugins: [
    [
      require.resolve('docusaurus-plugin-bruno'),
      {
        collectionsPath: './collections',
        outputPath: './docs/platform/api',
        includeExamples: true,
        includeAuth: true,
        folderAsPage: false,
        flattenVersions: false,
        excludePatterns: ['**/folder.bru', '**/bruno.json']
      }
    ]
  ],
  // ... rest of config
};

export default config;

Standalone Generator

The plugin includes a standalone generator command that can be run independently of Docusaurus:

# Generate docs using positional arguments (required)
generate-bruno-docs <input-path> <output-path>

# Example with paths
generate-bruno-docs ./collections ./docs/api

# Or via npx
npx generate-bruno-docs ./collections ./docs/api

# With environment variables (alternative to positional arguments)
BRUNO_INPUT=./my-collections BRUNO_OUTPUT=./docs/api generate-bruno-docs

# Show help
generate-bruno-docs --help

Environment Variables

• BRUNO_INPUT - Path to Bruno collections directory (required if not provided as first positional argument)
• BRUNO_OUTPUT - Output directory for generated docs (required if not provided as second positional argument)
• BRUNO_INCLUDE_EXAMPLES - Include code examples (default: true)
• BRUNO_INCLUDE_AUTH - Include auth information (default: true)
• BRUNO_FOLDER_AS_PAGE - Use folder-as-page mode (default: false)
• BRUNO_FLATTEN_VERSIONS - Flatten version folders (default: true for standalone generator)
• BRUNO_EXCLUDE_PATTERNS - Comma-separated list of exclude patterns

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | collectionsPath | string | './collections' | Path to Bruno collections directory | | outputPath | string | './docs/platform/api' | Output directory for generated docs | | includeExamples | boolean | true | Generate code examples | | includeAuth | boolean | true | Include authentication information | | folderAsPage | boolean | false | Group all requests in a folder into a single page | | flattenVersions | boolean | false | Flatten version folders (e.g., v1/, v2/) to show only highest version | | excludePatterns | string[] | ['**/folder.bru', '**/bruno.json'] | Files to exclude from processing |

Bruno File Format Support

The plugin supports the following Bruno file sections:

Meta Section

meta {
  name: Get session information
  type: http
  seq: 6
}

HTTP Methods

get {
  url: {{baseUrl}}/v1/auth/info
  body: json
  auth: inherit
}

Headers

headers {
  Content-Type: application/json
  Authorization: Bearer {{token}}
}

Authentication

auth:apikey {
  key: session
  value: {{API_KEY}}
  placement: header
}

Documentation

docs {
  Verify user factors and return session information
}

Generated Documentation

The plugin generates comprehensive API documentation including:

• HTTP Method Badges: Color-coded span elements with CSS classes (GET=green, POST=blue, etc.)
• Full URL: With environment variable substitution
• Request Body: JSON body content when present
• Query Parameters: Formatted list with descriptions
• Request/Response Headers: Formatted list with descriptions
• Documentation: Description and additional content from Bruno docs section
• Sidebar Positioning: Automatic sidebar ordering based on seq metadata

Example Output

---
sidebar_position: 6
---

# Get session information

<span className="http-method-get">GET</span> `/v1/auth/info`

Verify user factors and return session information

### Headers

- `Content-Type` - Type of content being sent *(Example: `application/json`)*

### Request Body

```json
{
  // Request body content here
}

## Usage

The plugin will automatically process Bruno files during the Docusaurus build process. In development mode, the plugin watches for file changes and regenerates documentation automatically.

When you run:
- `npm start` - The plugin automatically generates documentation before starting the dev server
- `npm run build` - The plugin automatically generates documentation before building

## License

MIT License - see LICENSE file for details.