Configuration Files

Complete reference for all DeepWikiOpen configuration files and options

Configuration Files Reference

DeepWikiOpen uses multiple configuration files to control various aspects of documentation generation, embedding, and deployment. This guide covers all configuration options with complete examples and best practices.

Configuration Overview

DeepWikiOpen configuration follows a hierarchical structure:

project-root/
├── generator.json       # Main generation config
├── embedder.json       # Embedding settings
├── repo.json          # Repository filters
├── .env               # Environment variables
├── docker-compose.yml # Docker configuration
└── config/            # Custom config directory
    ├── overrides.json
    └── templates/

1. generator.json Structure

The main configuration file controlling documentation generation and AI model selection.

Complete Schema

{
  "$schema": "https://deepwikiopen.com/schemas/generator.json",
  "version": "2.0",
  "name": "project-name",
  "description": "Project description",
  "ai": {
    "openai": {
      "default_model": "gpt-5",
      "supportsCustomModel": true,
      "models": {
        "gpt-5": {
          "temperature": 1.0
        },
        "gpt-4o": {
          "temperature": 0.7,
          "top_p": 0.8
        },
        "gpt-4o-mini": {
          "temperature": 0.8
        }
      }
    },
    "google": {
      "default_model": "gemini-2.0-flash-thinking-exp-1219",
      "models": {
        "gemini-2.0-flash-thinking-exp-1219": {},
        "gemini-1.5-flash": {},
        "gemini-1.5-pro": {}
      }
    }
  },
  "output": {
    "directory": "./docs",
    "format": "mdx",
    "clean": true,
    "preserveStructure": true
  },
  "source": {
    "directories": ["src", "lib"],
    "extensions": [".ts", ".tsx", ".js", ".jsx"],
    "exclude": ["**/*.test.*", "**/node_modules/**"],
    "followSymlinks": false
  },
  "parsing": {
    "parser": "typescript",
    "parserOptions": {
      "ecmaVersion": 2022,
      "sourceType": "module",
      "ecmaFeatures": {
        "jsx": true
      }
    },
    "plugins": ["jsdoc", "typescript"]
  },
  "generation": {
    "includePrivate": false,
    "includeInternal": false,
    "groupBy": "category",
    "sortBy": "alphabetical",
    "template": "default",
    "customTemplates": "./templates"
  },
  "features": {
    "searchIndex": true,
    "apiReference": true,
    "changelog": true,
    "examples": true,
    "playground": false
  },
  "metadata": {
    "author": "Your Name",
    "license": "MIT",
    "repository": "https://github.com/user/repo",
    "homepage": "https://project.com"
  }
}

Key Options Explained

Output Configuration

{
  "output": {
    "directory": "./docs",        // Output directory path
    "format": "mdx",             // Output format: mdx, markdown, html
    "clean": true,               // Clean output dir before generation
    "preserveStructure": true,   // Maintain source directory structure
    "assets": "./assets",        // Static assets directory
    "publicPath": "/docs"        // Base path for deployment
  }
}

Source Configuration

{
  "source": {
    "directories": ["src", "lib", "packages/**/src"],
    "extensions": [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"],
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/node_modules/**",
      "**/dist/**",
      "**/.next/**"
    ],
    "include": ["README.md", "CHANGELOG.md"],
    "followSymlinks": false,
    "maxDepth": 10
  }
}

Advanced Parsing Options

{
  "parsing": {
    "parser": "typescript",
    "parserOptions": {
      "ecmaVersion": 2022,
      "sourceType": "module",
      "ecmaFeatures": {
        "jsx": true,
        "decorators": true,
        "dynamicImport": true
      }
    },
    "tsconfig": "./tsconfig.json",
    "plugins": ["jsdoc", "typescript", "flow"],
    "customParsers": {
      ".vue": "vue-parser",
      ".svelte": "svelte-parser"
    }
  }
}

AI Model Configuration (Updated)

As of commit 05693d5, DeepWiki now supports GPT-5 as the default OpenAI model. Configure AI providers in generator.json:

{
  "ai": {
    "openai": {
      "default_model": "gpt-5",  // Now the default model
      "supportsCustomModel": true,
      "models": {
        "gpt-5": {
          "temperature": 1.0,
          "description": "Latest generation model with advanced reasoning"
        },
        "gpt-4o": {
          "temperature": 0.7,
          "top_p": 0.8,
          "description": "Previous default, still available as fallback"
        }
      }
    },
    "google": {
      "default_model": "gemini-2.0-flash-thinking-exp-1219",
      "models": {
        "gemini-2.0-flash-thinking-exp-1219": {
          "description": "Latest Gemini model with enhanced capabilities"
        }
      }
    },
    "azure": {
      "default_model": "gpt-5",
      "deployment_name": "gpt-5-deployment",
      "api_version": "2025-01-01-preview"
    }
  }
}

Important GPT-5 Requirements:

• Ensure your OpenAI account has GPT-5 API access
• GPT-5 may have regional availability limitations
• Pricing may differ from GPT-4o models
• Consider using GPT-4o as a fallback when GPT-5 is unavailable

2. embedder.json Configuration

Controls vector embedding generation for semantic search.

Complete Schema

{
  "$schema": "https://deepwikiopen.com/schemas/embedder.json",
  "version": "1.0",
  "model": {
    "provider": "openai",
    "name": "text-embedding-3-small",
    "dimensions": 1536,
    "maxTokens": 8192
  },
  "processing": {
    "chunkSize": 1000,
    "chunkOverlap": 200,
    "minChunkSize": 100,
    "splitter": "recursive",
    "batchSize": 100
  },
  "storage": {
    "type": "chroma",
    "path": "./embeddings",
    "collection": "docs",
    "persistence": true
  },
  "indexing": {
    "includeCode": true,
    "includeComments": true,
    "includeDocstrings": true,
    "languages": ["typescript", "javascript", "python"],
    "metadata": {
      "extractTags": true,
      "extractAuthors": true,
      "extractDates": true
    }
  },
  "optimization": {
    "cache": true,
    "cacheDir": "./.embedding-cache",
    "parallel": true,
    "workers": 4
  }
}

Provider-Specific Configurations

OpenAI Configuration

{
  "model": {
    "provider": "openai",
    "name": "text-embedding-3-large",
    "dimensions": 3072,
    "apiKey": "${OPENAI_API_KEY}",
    "baseUrl": "https://api.openai.com/v1"
  }
}

Ollama Configuration

{
  "model": {
    "provider": "ollama",
    "name": "nomic-embed-text",
    "dimensions": 768,
    "baseUrl": "http://localhost:11434"
  }
}

Hugging Face Configuration

{
  "model": {
    "provider": "huggingface",
    "name": "sentence-transformers/all-MiniLM-L6-v2",
    "dimensions": 384,
    "device": "cuda",
    "apiKey": "${HF_TOKEN}"
  }
}

3. repo.json File Filters

Controls file processing and repository limits.

Complete Schema

{
  "$schema": "https://deepwikiopen.com/schemas/repo.json",
  "version": "1.0",
  "filters": {
    "include": {
      "patterns": [
        "src/**/*.{ts,tsx,js,jsx}",
        "lib/**/*.{ts,tsx,js,jsx}",
        "docs/**/*.{md,mdx}"
      ],
      "minSize": 0,
      "maxSize": 1048576
    },
    "exclude": {
      "patterns": [
        "**/node_modules/**",
        "**/.git/**",
        "**/dist/**",
        "**/coverage/**",
        "**/*.min.js"
      ],
      "dotfiles": true,
      "vendored": true,
      "generated": true
    }
  },
  "limits": {
    "maxFiles": 10000,
    "maxFileSize": 5242880,
    "maxTotalSize": 104857600,
    "maxDepth": 20
  },
  "processing": {
    "detectLanguage": true,
    "extractMetadata": true,
    "parseImports": true,
    "analyzeDependencies": true
  },
  "languages": {
    "typescript": {
      "extensions": [".ts", ".tsx"],
      "parser": "typescript"
    },
    "javascript": {
      "extensions": [".js", ".jsx", ".mjs"],
      "parser": "babel"
    },
    "python": {
      "extensions": [".py"],
      "parser": "python"
    }
  }
}

Advanced Filtering Examples

{
  "filters": {
    "include": {
      "patterns": [
        "packages/*/src/**/*.ts",
        "!packages/*/src/**/*.test.ts"
      ],
      "rules": [
        {
          "pattern": "*.config.js",
          "maxSize": 102400
        }
      ]
    },
    "exclude": {
      "patterns": ["**/temp/**"],
      "keywords": ["GENERATED", "AUTO-GENERATED"],
      "licenses": ["proprietary", "confidential"]
    }
  }
}

4. Environment Variables Reference

Core Variables

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
HF_TOKEN=hf_...

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/deepwiki
REDIS_URL=redis://localhost:6379

# Storage
S3_BUCKET=deepwiki-docs
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

# Server Configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info

# Feature Flags
ENABLE_EMBEDDINGS=true
ENABLE_SEARCH=true
ENABLE_ANALYTICS=false
ENABLE_CACHE=true

# Security
JWT_SECRET=your-secret-key
ENCRYPTION_KEY=your-encryption-key
ALLOWED_ORIGINS=https://example.com,https://app.example.com

# Limits
MAX_FILE_SIZE=5MB
MAX_REQUEST_SIZE=10MB
RATE_LIMIT_WINDOW=15m
RATE_LIMIT_MAX=100

Development Variables

# Development
DEV_MODE=true
HOT_RELOAD=true
VERBOSE_LOGGING=true
SKIP_AUTH=true

# Testing
TEST_DATABASE_URL=postgresql://test:test@localhost:5432/test
MOCK_EMBEDDINGS=true

5. Docker Configuration

docker-compose.yml

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=redis://redis:6379
    ports:
      - "3000:3000"
    volumes:
      - ./docs:/app/docs
      - ./config:/app/config:ro
    depends_on:
      - postgres
      - redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: deepwiki
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./docs:/usr/share/nginx/html:ro
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - app

volumes:
  postgres_data:
  redis_data:

Dockerfile Configuration

FROM node:20-alpine AS builder

WORKDIR /app

# Copy configuration files
COPY package*.json ./
COPY generator.json embedder.json repo.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source
COPY . .

# Build
RUN npm run build

# Production stage
FROM node:20-alpine

WORKDIR /app

# Copy built application
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/*.json ./

# Create non-root user
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001

# Set ownership
RUN chown -R nodejs:nodejs /app

USER nodejs

EXPOSE 3000

CMD ["node", "dist/index.js"]

6. Custom Configuration Directory

Directory Structure

config/
├── environments/
│   ├── development.json
│   ├── staging.json
│   └── production.json
├── features/
│   ├── search.json
│   ├── embeddings.json
│   └── analytics.json
├── overrides.json
└── templates/
    ├── page.mdx
    └── component.mdx

Environment-Specific Config

// config/environments/production.json
{
  "extends": "../generator.json",
  "output": {
    "directory": "/var/www/docs",
    "publicPath": "https://docs.example.com"
  },
  "features": {
    "playground": false,
    "analytics": true
  },
  "optimization": {
    "minify": true,
    "compress": true,
    "cache": true
  }
}

Feature Toggles

// config/features/search.json
{
  "search": {
    "enabled": true,
    "provider": "algolia",
    "config": {
      "appId": "${ALGOLIA_APP_ID}",
      "apiKey": "${ALGOLIA_API_KEY}",
      "indexName": "docs"
    },
    "options": {
      "facets": ["category", "tags", "language"],
      "snippetLength": 200,
      "highlightPreTag": "<mark>",
      "highlightPostTag": "</mark>"
    }
  }
}

7. Configuration Inheritance and Overrides

Inheritance Chain

// Configuration precedence (highest to lowest):
1. Environment variables
2. CLI arguments
3. Override files
4. Environment-specific configs
5. Base configuration files
6. Default values

Override Example

// config/overrides.json
{
  "extends": ["./generator.json", "./environments/production.json"],
  "merge": {
    "output": {
      "directory": "/custom/path"
    }
  },
  "replace": {
    "features": {
      "playground": true
    }
  }
}

Programmatic Configuration

// config.js
module.exports = {
  generator: {
    async beforeGenerate(config) {
      // Dynamic configuration
      if (process.env.ENABLE_BETA_FEATURES) {
        config.features.beta = true;
      }
      return config;
    },
    
    async afterGenerate(result, config) {
      // Post-processing
      console.log(`Generated ${result.files.length} files`);
    }
  }
};

8. Best Practices

1. Use Environment Variables for Secrets

{
  "api": {
    "key": "${API_KEY}",
    "secret": "${API_SECRET}"
  }
}

2. Separate Concerns

config/
├── generation.json    # Documentation generation
├── deployment.json    # Deployment settings
├── security.json      # Security policies
└── performance.json   # Performance tuning

3. Version Control Strategy

# .gitignore
.env
.env.local
config/secrets.json
config/production.json

4. Validation

// validate-config.js
const { validateConfig } = require('deepwikiopen');

async function validate() {
  try {
    await validateConfig('./generator.json');
    console.log('Configuration is valid');
  } catch (error) {
    console.error('Configuration error:', error);
    process.exit(1);
  }
}

5. Configuration Templates

// config/templates/microservice.json
{
  "name": "${SERVICE_NAME}",
  "source": {
    "directories": ["./src"],
    "extensions": [".ts"]
  },
  "output": {
    "directory": "./docs/${SERVICE_NAME}"
  }
}

9. Security Considerations

Sensitive Data Protection

{
  "security": {
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm",
      "keySource": "env:ENCRYPTION_KEY"
    },
    "secrets": {
      "provider": "vault",
      "endpoint": "${VAULT_ENDPOINT}",
      "namespace": "deepwiki"
    }
  }
}

Access Control

{
  "access": {
    "authentication": {
      "required": true,
      "providers": ["oauth", "saml"]
    },
    "authorization": {
      "roles": {
        "admin": ["*"],
        "developer": ["read", "generate"],
        "viewer": ["read"]
      }
    }
  }
}

Audit Configuration

{
  "audit": {
    "enabled": true,
    "events": ["config.changed", "generation.started", "generation.completed"],
    "retention": "30d",
    "storage": "s3://audit-logs"
  }
}

10. Migration Between Versions

Version 1.x to 2.x Migration

// migrate-config.js
const { migrateConfig } = require('deepwikiopen/migrate');

async function migrate() {
  const oldConfig = require('./generator.v1.json');
  
  const newConfig = await migrateConfig(oldConfig, {
    from: '1.x',
    to: '2.x',
    transforms: {
      // Custom transformations
      'output.path': 'output.directory',
      'parse.include': 'source.extensions'
    }
  });
  
  await fs.writeFile('./generator.json', JSON.stringify(newConfig, null, 2));
}

Breaking Changes Checklist

## Migration Checklist

- [ ] Backup existing configuration
- [ ] Update schema version
- [ ] Rename deprecated fields
- [ ] Update environment variables
- [ ] Test with dry-run
- [ ] Update CI/CD pipelines
- [ ] Update documentation

Compatibility Mode

{
  "version": "2.0",
  "compatibility": {
    "mode": "1.x",
    "warnings": true,
    "strict": false
  }
}

Configuration Debugging

Debug Mode

# Enable debug logging
DEBUG=deepwiki:config npm run generate

# Validate configuration
npm run validate-config

# Show resolved configuration
npm run show-config

Common Issues

1. Path Resolution

   {
     "paths": {
       "base": "${__dirname}",
       "resolve": ["node_modules", "../shared"]
     }
   }
   

2. Environment Variable Expansion

   {
     "database": {
       "url": "${DATABASE_URL:-postgresql://localhost:5432/dev}"
     }
   }
   

3. Circular Dependencies

   {
     "extends": "./base.json",
     "validate": {
       "circular": false
     }
   }
   

Next Steps

• Environment Setup Guide
• Security Best Practices
• Performance Tuning
• Troubleshooting Guide