# Smart Mind Map - Mind Mapping Generation Plugin

**Author:** [Fu-Jie](https://github.com/Fu-Jie) | **Version:** 0.9.1 | **License:** MIT

> **Important**: To ensure the maintainability and usability of all plugins, each plugin should be accompanied by clear and comprehensive documentation to ensure its functionality, configuration, and usage are well explained.

Smart Mind Map is a powerful OpenWebUI action plugin that intelligently analyzes long-form text content and automatically generates interactive mind maps, helping users structure and visualize knowledge.

---

## 🔥 What's New in v0.9.1

**New Feature: Image Output Mode**

- **Static Image Support**: Added `OUTPUT_MODE` configuration parameter.
  - `html` (default): Interactive HTML mind map.
  - `image`: Static SVG image embedded directly in Markdown (**No HTML code output**, cleaner chat history).
- **Efficient Storage**: Image mode uploads SVG to `/api/v1/files`, avoiding huge base64 strings in chat history.
- **Smart Features**: Auto-responsive width and automatic theme detection (light/dark) for generated images.

| Feature | HTML Mode (Default) | Image Mode |
| :--- | :--- | :--- |
| **Output Format** | Interactive HTML Block | Static Markdown Image |
| **Interactivity** | Zoom, Pan, Expand/Collapse | None (Static Image) |
| **Chat History** | Contains HTML Code | Clean (Image URL only) |
| **Storage** | Browser Rendering | `/api/v1/files` Upload |

---

## Core Features

- ✅ **Intelligent Text Analysis**: Automatically identifies core themes, key concepts, and hierarchical structures
- ✅ **Interactive Visualization**: Generates beautiful interactive mind maps based on Markmap.js
- ✅ **High-Resolution PNG Export**: Export mind maps as high-quality PNG images (9x scale, ~1-2MB file size)
- ✅ **Complete Control Panel**: Zoom controls (+/-/reset), expand level selection (All/2/3 levels), and fullscreen mode
- ✅ **Theme Switching**: Manual theme toggle button (light/dark) with automatic theme detection
- ✅ **Dark Mode Support**: Full dark mode support with automatic detection and manual override
- ✅ **Multi-language Support**: Automatically adjusts output based on user language
- ✅ **Real-time Rendering**: Renders mind maps directly in the chat interface without navigation
- ✅ **Export Capabilities**: Supports PNG, SVG code, and Markdown source export
- ✅ **Customizable Configuration**: Configurable LLM model, minimum text length, and other parameters
- ✅ **Image Output Mode**: Generate static SVG images embedded directly in Markdown (**No HTML code output**, cleaner chat history)

---

## How It Works

1. **Text Extraction**: Extracts text content from user messages (automatically filters HTML code blocks)
2. **Intelligent Analysis**: Analyzes text structure using the configured LLM model
3. **Markdown Generation**: Converts analysis results to Markmap-compatible Markdown format
4. **Visual Rendering**: Renders the mind map using Markmap.js in an HTML template with optimized font hierarchy (H1: 22px bold, H2: 18px bold)
5. **Interactive Display**: Presents the mind map to users in an interactive format with complete control panel
6. **Theme Detection**: Automatically detects and applies the current OpenWebUI theme (light/dark mode)
7. **Export Options**: Provides PNG (high-resolution), SVG, and Markdown export functionality

---

## Installation and Configuration

### 1. Plugin Installation

1. Download the `smart_mind_map_cn.py` file to your local computer
2. In OpenWebUI Admin Settings, find the "Plugins" section
3. Select "Actions" type
4. Upload the downloaded file
5. Refresh the page, and the plugin will be available

### 2. Model Configuration

The plugin requires access to an LLM model for text analysis. Please ensure:

- Your OpenWebUI instance has at least one available LLM model configured
- Recommended to use fast, economical models (e.g., `gemini-2.5-flash`) for the best experience
- Configure the `LLM_MODEL_ID` parameter in the plugin settings

### 3. Plugin Activation

Select the "Smart Mind Map" action plugin in chat settings to enable it.

### 4. Theme Color Consistency (Optional)

To keep the mind map visually consistent with the OpenWebUI theme colors, enable same-origin access for artifacts in OpenWebUI:

- **Configuration Location**: In OpenWebUI User Settings: **Interface** → **Artifacts** → **iframe Sandbox Allow Same Origin**
- **Enable Option**: Check the "Allow same-origin access for artifacts" / "iframe sandbox allow-same-origin" option
- **Sandbox Attributes**: Ensure the iframe's sandbox attribute includes both `allow-same-origin` and `allow-scripts`

Once enabled, the mind map will automatically detect and apply the current OpenWebUI theme (light/dark) without any manual configuration.

---

## Configuration Parameters

You can adjust the following parameters in the plugin's settings (Valves):

| Parameter | Default | Description |
| :--- | :--- | :--- |
| `show_status` | `true` | Whether to display operation status updates in the chat interface (e.g., "Analyzing..."). |
| `LLM_MODEL_ID` | `gemini-2.5-flash` | LLM model ID for text analysis. Recommended to use fast and economical models. |
| `MIN_TEXT_LENGTH` | `100` | Minimum text length (in characters) required for mind map analysis. Text that's too short cannot generate valid mind maps. |
| `CLEAR_PREVIOUS_HTML` | `false` | Whether to clear previous plugin-generated HTML content when generating a new mind map. |
| `MESSAGE_COUNT` | `1` | Number of recent messages to use for mind map generation (1-5). |
| `OUTPUT_MODE` | `html` | Output mode: `html` for interactive HTML (default), or `image` to embed as static Markdown image. |

---

## Usage

### Basic Usage

1. Enable the "Smart Mind Map" action in chat settings
2. Input or paste long-form text content (at least 100 characters) in the conversation
3. After sending the message, the plugin will automatically analyze and generate a mind map
4. The mind map will be rendered directly in the chat interface

### Usage Example

**Input Text:**

```
Artificial Intelligence (AI) is a branch of computer science dedicated to creating systems capable of performing tasks that typically require human intelligence.
Main application areas include:
1. Machine Learning - Enables computers to learn from data
2. Natural Language Processing - Understanding and generating human language
3. Computer Vision - Recognizing and processing images
4. Robotics - Creating intelligent systems that can interact with the physical world
```

**Generated Result:**
The plugin will generate an interactive mind map centered on "Artificial Intelligence", including major application areas and their sub-concepts.

### Export Features

Generated mind maps support three export methods:

1. **Download PNG**: Click the "📥 Download PNG" button to export the mind map as a high-resolution PNG image (9x scale, ~1-2MB file size)
2. **Copy SVG Code**: Click the "Copy SVG Code" button to copy the mind map in SVG format to the clipboard
3. **Copy Markdown**: Click the "Copy Markdown" button to copy the raw Markdown format to the clipboard

### Control Panel

The interactive mind map includes a comprehensive control panel:

- **Zoom Controls**: `+` (zoom in), `-` (zoom out), `↻` (reset view)
- **Expand Level**: Switch between "All", "2 Levels", "3 Levels" to control node expansion depth
- **Fullscreen**: Enter fullscreen mode for better viewing experience
- **Theme Toggle**: Manually switch between light and dark themes

---

## Technical Architecture

### Frontend Rendering

- **Markmap.js**: Open-source mind mapping rendering engine
- **D3.js**: Data visualization foundation library
- **Responsive Design**: Adapts to different screen sizes
- **Font Hierarchy**: Optimized typography with H1 (22px bold) and H2 (18px bold) for better readability

### PNG Export Technology

- **SVG to Canvas Conversion**: Converts mind map SVG to canvas for PNG export
- **ForeignObject Handling**: Properly processes HTML content within SVG elements
- **High Resolution**: 9x scale factor for print-quality output (~1-2MB file size)
- **Theme Preservation**: Maintains current theme (light/dark) in exported PNG

### Theme Detection Mechanism

Automatically detects and applies themes with a 4-level priority:

1. **Explicit Toggle**: User manually clicks theme toggle button (highest priority)
2. **Meta Tag**: Reads `<meta name="theme-color">` from parent document
3. **Class/Data-Theme**: Checks `class` or `data-theme` attributes on parent HTML/body
4. **System Preference**: Falls back to `prefers-color-scheme` media query

### Backend Processing

- **LLM Integration**: Calls configured models via `generate_chat_completion`
- **Text Preprocessing**: Automatically filters HTML code blocks, extracts plain text content
- **Format Conversion**: Converts LLM output to Markmap-compatible Markdown format

### Security Enhancements

- **XSS Protection**: Automatically escapes `</script>` tags to prevent script injection
- **Input Validation**: Checks text length to avoid invalid requests
- **Non-Bubbling Events**: Button clicks use `stopPropagation()` to prevent navigation interception

---

## Troubleshooting

### Issue: Plugin Won't Start

**Solution:**

- Check OpenWebUI logs for error messages
- Confirm the plugin is correctly uploaded and enabled
- Verify OpenWebUI version supports action plugins

### Issue: Text Content Too Short

**Symptom:** Prompt shows "Text content is too short for effective analysis"

**Solution:**

- Ensure input text contains at least 100 characters (default configuration)
- Lower the `MIN_TEXT_LENGTH` parameter value in plugin settings
- Provide more detailed, structured text content

### Issue: Mind Map Not Generated

**Solution:**

- Check if `LLM_MODEL_ID` is configured correctly
- Confirm the configured model is available in OpenWebUI
- Review backend logs for LLM call failures
- Verify user has sufficient permissions to access the configured model

### Issue: Mind Map Display Error

**Symptom:** Shows "⚠️ Mind map rendering failed"

**Solution:**

- Check browser console for error messages
- Confirm Markmap.js and D3.js libraries are loading correctly
- Verify generated Markdown format conforms to Markmap specifications
- Try refreshing the page to re-render

### Issue: PNG Export Not Working

**Symptom:** PNG download button doesn't work or produces blank/corrupted images

**Solution:**

- Ensure browser supports HTML5 Canvas API (all modern browsers do)
- Check browser console for errors related to `toDataURL()` or canvas rendering
- Verify the mind map is fully rendered before clicking export
- Try refreshing the page and re-generating the mind map
- Use Chrome or Firefox for best PNG export compatibility

### Issue: Theme Not Auto-Detected

**Symptom:** Mind map doesn't match OpenWebUI theme colors

**Solution:**

- Enable "iframe Sandbox Allow Same Origin" in OpenWebUI Settings → Interface → Artifacts
- Verify the iframe's sandbox attribute includes both `allow-same-origin` and `allow-scripts`
- Ensure parent document has `<meta name="theme-color">` tag or theme class/attribute
- Use the manual theme toggle button to override automatic detection
- Check browser console for cross-origin errors

### Issue: Export Function Not Working

**Solution:**

- Confirm browser supports Clipboard API
- Check if browser is blocking clipboard access permissions
- Use modern browsers (Chrome, Firefox, Edge, etc.)

---

## Best Practices

1. **Text Preparation**
   - Provide text content with clear structure and distinct hierarchies
   - Use paragraphs, lists, and other formatting to help LLM understand text structure
   - Avoid excessively lengthy or unstructured text

2. **Model Selection**
   - For daily use, recommend fast models like `gemini-2.5-flash`
   - For complex text analysis, use more powerful models (e.g., GPT-4)
   - Balance speed and analysis quality based on needs

3. **Performance Optimization**
   - Set `MIN_TEXT_LENGTH` appropriately to avoid processing text that's too short
   - For particularly long texts, consider summarizing before generating mind maps
   - Disable `show_status` in production environments to reduce interface updates

4. **Export Quality**
   - **PNG Export**: Best for presentations, documents, and sharing (9x resolution suitable for printing)
   - **SVG Export**: Best for further editing in vector graphics tools (infinite scalability)
   - **Markdown Export**: Best for version control, collaboration, and regeneration

5. **Theme Consistency**
   - Enable same-origin access for automatic theme detection
   - Use manual theme toggle if automatic detection fails
   - Export PNG after switching to desired theme for consistent visuals

---

## Requirements

This plugin uses only OpenWebUI's built-in dependencies. **No additional packages need to be installed.**

---

## Changelog

### v0.9.1

**New Feature: Image Output Mode**

- Added `OUTPUT_MODE` configuration parameter with two options:
  - `html` (default): Interactive HTML mind map with full control panel
  - `image`: Static SVG image embedded directly in Markdown (uploaded to `/api/v1/files`)
- Image mode features:
  - Auto-responsive width (adapts to chat container)
  - Automatic theme detection (light/dark)
  - Persistent storage via Chat API (survives page refresh)
  - Efficient file storage (no huge base64 strings in chat history)

**Improvements:**

- Implemented robust Chat API update mechanism with retry logic
- Fixed message persistence using both `messages[]` and `history.messages`
- Added Event API for immediate frontend updates
- Removed unnecessary `SVG_WIDTH` and `SVG_HEIGHT` parameters (now auto-calculated)

**Technical Details:**

- Image mode uses `__event_call__` to execute JavaScript in the browser
- SVG is rendered offline, converted to Blob, and uploaded to OpenWebUI Files API
- Updates chat message with `/api/v1/files/{id}/content` URL via OpenWebUI Backend-Controlled API flow

### v0.8.2

- Removed debug messages from output

### v0.8.0 (Previous Version)

**Major Features:**

- Added high-resolution PNG export (9x scale, ~1-2MB file size)
- Implemented complete control panel with zoom controls (+/-/reset)
- Added expand level selection (All/2/3 levels)
- Integrated fullscreen mode with auto-fit
- Added manual theme toggle button (light/dark)
- Implemented automatic theme detection with 4-level priority

**Improvements:**

- Optimized font hierarchy (H1: 22px bold, H2: 18px bold)
- Enhanced dark mode with full theme support
- Improved PNG export technology (SVG to Canvas with foreignObject handling)
- Added theme preservation in exported PNG images
- Enhanced security with non-bubbling button events

**Bug Fixes:**

- Fixed theme detection in cross-origin iframes
- Resolved PNG export issues with HTML content in SVG
- Improved compatibility with OpenWebUI theme system

### v0.7.2

- Optimized text extraction logic, automatically filters HTML code blocks
- Improved error handling and user feedback
- Enhanced export functionality compatibility
- Optimized UI styling and interactive experience

---

## License

This plugin is released under the MIT License.

## Contributing

Welcome to submit issue reports and improvement suggestions! Please visit the project repository: [awesome-openwebui](https://github.com/Fu-Jie/awesome-openwebui)

---

## Related Resources

- [Markmap Official Website](https://markmap.js.org/)
- [OpenWebUI Documentation](https://docs.openwebui.com/)
- [D3.js Official Website](https://d3js.org/)