Illustrate

Adds images to markdown documents. Analyzes the content, determines appropriate image locations, generates or finds images, and optionally reviews them for quality.

The workflow:

1. Analyzes document structure and content
2. Plans image locations (header + additional placements)
3. Generates images in parallel (photos, AI-generated, or diagrams)
4. Optionally reviews images with vision model
5. Retries failed generations if needed
6. Inserts images into the document

When to Use This

This workflow is intended for adding visual elements to completed documents—making articles more engaging before publication.

For creating the underlying content, use Web Research, Literature Review, or Evening Reads.

How It Works

flowchart TD
    subgraph analyze["1. Analysis"]
        A[Your Document] --> B[Analyze Structure]
        B --> C[Plan Image Locations]
    end

    subgraph generate["2. Generation"]
        C --> D1[Generate Header Image]
        C --> D2[Generate Image 2]
        C --> D3[Generate Image 3]
        C --> D4[...]
    end

    subgraph review["3. Review (Optional)"]
        D1 --> E{Vision Review?}
        D2 --> E
        D3 --> E
        D4 --> E
        E -->|Yes| F[Review Each Image]
        E -->|No| G[Skip to Finalize]
        F --> H{Passed?}
        H -->|No| I[Retry Generation]
        I --> F
        H -->|Yes| G
    end

    subgraph finish["4. Finalize"]
        G --> J[Save Images]
        J --> K[Insert into Document]
    end

    K --> L[Illustrated Document]

    style analyze fill:#e8f4f8
    style generate fill:#f0f8e8
    style review fill:#fff8e8
    style finish fill:#f8e8f4

The Steps Explained

1. Analysis Reads the document and identifies where images would be valuable. Plans a header image plus 0-5 additional images at natural break points.

2. Generation Generates all planned images in parallel. Three image types:

• Public domain photos: Fetched from Pexels/Unsplash based on semantic search
• AI-generated images: Created via Google Imagen for concepts that need custom visuals
• SVG diagrams: Generated by Claude for technical concepts, processes, or relationships

3. Review (Optional) If enabled, uses a vision model to evaluate each generated image. Checks for relevance, quality, and appropriateness. Failed images can be regenerated with adjusted prompts.

4. Finalize Saves images to the specified output directory and inserts markdown image references into the document.

Inputs

Input	Description	Example
Document	Markdown content to illustrate	Your article or report
Title (optional)	Document title for context	”The Future of Remote Work”
Output directory (optional)	Where to save images	”./images/“
Config	Settings (see below)	IllustrateConfig object

Configuration Options

Option	Description	Default
Generate header image	Whether to create a header	true
Additional image count	Images beyond header (0-5)	3
Enable vision review	Review images with vision model	true
Max retries	Retry attempts for failed images	2
Diagram quality threshold	Minimum score for SVG diagrams (1-5)	3

Outputs

Output	Description
Illustrated document	Markdown with image references inserted
Images	Saved image files with metadata
Status	Success, partial, or failed

Image Types

Public Domain Photos Best for: Evocative imagery, emotional resonance, familiar concepts. Source: Pexels, Unsplash (free, attribution-free).

AI-Generated Images Best for: Abstract concepts, custom scenes, specific visual needs. Source: Google Imagen.

SVG Diagrams Best for: Processes, relationships, technical concepts, comparisons. Source: Claude-generated, rendered to PNG.

Example

Input:

• Document: 3,000-word article on “Building a Second Brain”
• Config: Header + 3 additional images, vision review enabled

Typical output:

• Header: AI-generated image of interconnected nodes representing knowledge
• Image 2: Diagram showing capture → organize → distill → express workflow
• Image 3: Photo of person working with notebooks and digital tools
• Image 4: Diagram comparing different note-taking systems

---

Developer Reference

Entry point: workflows/output/illustrate/graph.py — illustrate_graph

Graph construction: Same file — create_illustrate_graph()

State: workflows/output/illustrate/state.py — IllustrateState

Config: workflows/output/illustrate/config.py — IllustrateConfig dataclass

Nodes: workflows/output/illustrate/nodes/

• analyze_document.py — structure analysis and image planning
• generate_header.py — header image generation
• generate_additional.py — additional image generation
• review_image.py — vision model quality review
• finalize.py — save files and insert references

Schemas: workflows/output/illustrate/schemas.py — ImageLocationPlan, generation result models

Prompts: workflows/output/illustrate/prompts.py — image prompt generation