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):
Environment variables
CLI arguments
Override files
Environment-specific configs
Base configuration files
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

Path Resolution

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

Environment Variable Expansion

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

Circular Dependencies

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

Get Started

Configuration

Advanced

Support

​Configuration Files Reference

​Configuration Overview

​1. generator.json Structure

​Complete Schema

​Key Options Explained

​Output Configuration

​Source Configuration

​Advanced Parsing Options

​AI Model Configuration (Updated)

​2. embedder.json Configuration

​Complete Schema

​Provider-Specific Configurations

​OpenAI Configuration

​Ollama Configuration

​Hugging Face Configuration

​3. repo.json File Filters

​Complete Schema

​Advanced Filtering Examples

​4. Environment Variables Reference

​Core Variables

​Development Variables

​5. Docker Configuration

​docker-compose.yml

​Dockerfile Configuration

​6. Custom Configuration Directory

​Directory Structure

​Environment-Specific Config

​Feature Toggles

​7. Configuration Inheritance and Overrides

​Inheritance Chain

​Override Example

​Programmatic Configuration

​8. Best Practices

​1. Use Environment Variables for Secrets

​2. Separate Concerns

​3. Version Control Strategy

​4. Validation

​5. Configuration Templates

​9. Security Considerations

​Sensitive Data Protection

​Access Control

​Audit Configuration

​10. Migration Between Versions

​Version 1.x to 2.x Migration

​Breaking Changes Checklist

​Compatibility Mode

​Configuration Debugging

​Debug Mode

​Common Issues

​Next Steps

Configuration Files Reference

Configuration Overview

1. generator.json Structure

Complete Schema

Key Options Explained

Output Configuration

Source Configuration

Advanced Parsing Options

AI Model Configuration (Updated)

2. embedder.json Configuration

Complete Schema

Provider-Specific Configurations

OpenAI Configuration

Ollama Configuration

Hugging Face Configuration

3. repo.json File Filters

Complete Schema

Advanced Filtering Examples

4. Environment Variables Reference

Core Variables

Development Variables

5. Docker Configuration

docker-compose.yml

Dockerfile Configuration

6. Custom Configuration Directory

Directory Structure

Environment-Specific Config

Feature Toggles

7. Configuration Inheritance and Overrides

Inheritance Chain

Override Example

Programmatic Configuration

8. Best Practices

1. Use Environment Variables for Secrets

2. Separate Concerns

3. Version Control Strategy

4. Validation

5. Configuration Templates

9. Security Considerations

Sensitive Data Protection

Access Control

Audit Configuration

10. Migration Between Versions

Version 1.x to 2.x Migration

Breaking Changes Checklist

Compatibility Mode

Configuration Debugging

Debug Mode

Common Issues

Next Steps