Configuration

Do it with an agent

Configure diagramkit for this repo. Read node_modules/diagramkit/llms.txt first. If the defaults (SVG, both themes, .diagramkit/ output dir, incremental rebuild) work, do nothing. Otherwise run npx diagramkit init --yes to scaffold diagramkit.config.json5, then edit only the fields this repo actually needs to override (formats, theme, outputDir, sameFolder, outputPrefix/Suffix).

For a TypeScript config with autocompletion: npx diagramkit init --ts.

Do it manually

diagramkit works with zero configuration. All settings have sensible defaults. When you need to customize, settings merge in this order (later sources override earlier):

1. Defaults — built-in values
2. Global config — ~/.config/diagramkit/config.json5 (also supports config.json)
3. Environment variables — DIAGRAMKIT_*
4. Local config — diagramkit.config.json5 or .ts (walks up from cwd)
5. CLI flags / API overrides — highest priority

Use --config <path> to point at a specific config file instead of auto-discovery. For a quick chooser, see Config Decision Matrix.

Config Files

Local (JSON5)

Place a diagramkit.config.json5 in your project root:

1{2  // Output folder name (default: .diagramkit)3  outputDir: '.diagramkit',4  defaultFormats: ['svg'],5  defaultTheme: 'both',6}

Create one with:

1diagramkit init

Legacy .diagramkitrc.json files are still supported but deprecated. Migrate to diagramkit.config.json5 for comment support and richer options.

Local (TypeScript)

For type-safe configuration:

1import { defineConfig } from 'diagramkit'23export default defineConfig({4  defaultFormats: ['svg'],5  defaultTheme: 'both',6})

Create one with:

1diagramkit init --ts

TypeScript configs are loaded via jiti at runtime — no build step needed.

Global

Machine-wide defaults at ~/.config/diagramkit/config.json5 (or $XDG_CONFIG_HOME/diagramkit/config.json5). config.json is also accepted in the same location:

1{2  defaultFormats: ['png'],3  defaultTheme: 'both',4}

Environment Variables

All Options

outputDir

• Type: string — Default: '.diagramkit'

Name of the output folder created next to source files.

manifestFile

• Type: string — Default: 'manifest.json'

Manifest filename inside the output folder. Tracks content hashes for incremental builds.

useManifest

• Type: boolean — Default: true

When false, all diagrams re-render every run and no manifest is written.

sameFolder

• Type: boolean — Default: false

Place outputs alongside source files instead of in a subdirectory. When true, outputDir is ignored.

defaultFormats

• Type: OutputFormat[] — Default: ['svg']

Array of output formats. Supports multiple formats in a single render pass.

1{ defaultFormats: ['svg', 'png'] }

defaultTheme

• Type: 'light' | 'dark' | 'both' — Default: 'both'

outputPrefix / outputSuffix

• Type: string — Default: ''

Prefix and suffix for output filenames:

1${outputPrefix}${name}${outputSuffix}-${theme}.${format}

inputDirs

• Type: string[] — Default: undefined (scan entire tree)

Restrict diagram file scanning to specific directories (relative to the project root). When set, only these directories are scanned instead of the full tree:

1{2  inputDirs: ['docs/diagrams', 'src/architecture'],3}

Useful in monorepos or projects where diagrams are concentrated in specific folders.

extensionMap

• Type: Record<string, DiagramType> — Default: built-in map

Custom extension-to-type mapping, merged with the built-in map:

1{2  extensionMap: {3    ".custom-diagram": "mermaid",4    ".service-map": "graphviz",5  },6}

Built-in extensions:

overrides

• Type: Record<string, FileOverride> — Default: undefined

Per-file render overrides. Keys can be exact filenames, relative paths, or glob patterns:

1{2  overrides: {3    // Exact filename — render hero as SVG + PNG at 3x4    "hero.mermaid": { formats: ["svg", "png"], scale: 3 },56    // Glob — all excalidraw files in docs/ get light theme only7    "docs/*.excalidraw": { theme: "light" },89    // Relative path — specific file gets high quality10    "src/diagrams/arch.drawio": { quality: 95 },11  },12}

Each FileOverride can set:

Example Configs

Minimal (defaults work for most projects)

1{}

Multi-format output

1{2  defaultFormats: ['svg', 'png'],3}

PNG, same folder

1{2  defaultFormats: ['png'],3  sameFolder: true,4}

CI pipeline (no caching)

1{2  useManifest: false,3  defaultFormats: ['png'],4}

Or via environment:

1DIAGRAMKIT_NO_MANIFEST=1 DIAGRAMKIT_FORMAT=png diagramkit render .

Per-file overrides

1{2  defaultFormats: ['svg'],3  overrides: {4    "hero.mermaid": { formats: ["svg", "png"], scale: 3 },5    "**/*.excalidraw": { theme: "light" },6  },7}

TypeScript with defineConfig

1import { defineConfig } from 'diagramkit'23export default defineConfig({4  defaultFormats: ['svg', 'png'],5  overrides: {6    'hero.mermaid': { formats: ['svg', 'png'], scale: 3 },7  },8})

Precedence Example

Given:

• Global: { defaultFormats: ['png'] }
• Env: DIAGRAMKIT_THEME=light
• Local: { defaultFormats: ['svg'], outputDir: '_diagrams' }
• CLI: diagramkit render . --format jpeg

Resolved: