ssshooter/mind-elixir-core/plaintext-format

Mind Elixir Plaintext Format

This skill explains the Mind Elixir plaintext format specification and how to convert between it and the Mind Elixir JSON data structure. The plaintext format is ideal for human editing, AI generation, and streaming scenarios.

1. Format Overview

The plaintext format uses indentation-based syntax similar to Markdown lists. Each line represents a node in the mind map, and indentation (2 spaces per level) defines the hierarchy.

Basic Structure

- Root Node
  - Child Node 1
    - Child Node 1-1
    - Child Node 1-2
  - Child Node 2
    - Child Node 2-1

Key Rules:

• Root node starts with - (dash followed by space)
• Each child is indented by 2 spaces relative to its parent
• Each node line starts with - followed by a space and the topic text

2. Advanced Features

2.1 Node References (IDs)

Assign custom IDs to nodes for cross-referencing using [^id] syntax:

- Root
  - Node A [^id1]
  - Node B [^id2]

Format: [^customId] at the end of the topic text.

2.2 Node Links

Create connections between nodes using the > prefix and arrow syntax:

Bidirectional Links

- Root
  - Node A [^id1]
  - Node B [^id2]
  - > [^id1] (10,20) <-Link Label-> (-10,-20) [^id2]

Format: > [^sourceId] (delta1X,delta1Y) <-Label-> (delta2X,delta2Y) [^targetId]

• (delta1X,delta1Y): Offset of the control point from the start node.
• (delta2X,delta2Y): Offset of the control point from the end node.

[!TIP]

Optional Coordinates: When manually writing or generating plaintext (e.g., via AI), you can omit the (x,y) coordinates. Mind Elixir will automatically calculate default balanced offsets when rendering. However, when you export data back to plaintext, these coordinates will be included to preserve any manual adjustments made in the UI.

Unidirectional Links

- Root
  - Node A [^id1]
  - Node B [^id2]
  - > [^id1] >-Forward Link-> [^id2]

Formats:

• Forward: > [^sourceId] >-Label-> [^targetId]

2.3 Node Styling

Apply inline styles using JSON-like syntax:

- Root
  - Styled Node {"color": "#e87a90"}
  - Another Node {"color": "#3298db", "background": "#ecf0f1"}

Format: {"property": "value", "property2": "value2"} at the end of the topic text.

Common Properties:

• color: Text color (hex code)
• background: Background color (hex code)
• fontSize: Font size (number as string, e.g., "16")

2.4 Summary Nodes

Create summary nodes that visually group previous siblings:

- Root
  - Node 1
  - Node 2
  - Node 3
  - } Summary of all above nodes

Formats:

• } Summary text - Summarizes all previous siblings
• }:N Summary text - Summarizes the previous N siblings (e.g., }:2 for last 2 nodes)

- Root
  - Node 1
  - Node 2
  - Node 3
  - }:2 Summary of Node 2 and Node 3

2.5 Complete Example

- Project Planning
  - Phase 1: Research [^phase1]
    - Market Analysis {"color": "#3298db"}
    - Competitor Study {"color": "#3298db"}
    - }:2 Research Summary
  - Phase 2: Development [^phase2]
    - Frontend {"color": "#2ecc71"}
    - Backend {"color": "#2ecc71"}
    - Testing {"color": "#f39c12"}
    - } Development Summary
  - Phase 3: Launch [^phase3]
    - Marketing
    - Deployment
  - > [^phase1] (50,0) >-Leads to-> (-50,0) [^phase2]
  - > [^phase2] >-Leads to-> [^phase3]

3. Conversion API

3.1 Plaintext to Mind Elixir Data

Mind Elixir provides a built-in converter for plaintext parsing:

import { plaintextToMindElixir } from 'mind-elixir/plaintextConverter'
const plaintext = `
- Root Node
  - Child 1
  - Child 2
`
const mindElixirData = plaintextToMindElixir(plaintext)
// Returns MindElixirData object ready for mind.init() or mind.refresh()

3.2 Mind Elixir Data to Plaintext

You can also convert an existing mind map back to the plaintext format, which is useful for exporting and saving data:

import { mindElixirToPlaintext } from 'mind-elixir/plaintextConverter'
const mindElixirData = mind.getAllData()
const plaintext = mindElixirToPlaintext(mindElixirData)
// Returns a string containing the mind map in plaintext format

3.3 Integration Example

import MindElixir from 'mind-elixir'
import { plaintextToMindElixir } from 'mind-elixir/plaintextConverter'
// 1. Parse plaintext
const plaintext = `
- My Mind Map
  - Topic 1
    - Subtopic 1.1
    - Subtopic 1.2
  - Topic 2
`
const data = plaintextToMindElixir(plaintext)
// 2. Initialize Mind Elixir
const mind = new MindElixir({
  el: '#map',
  direction: MindElixir.RIGHT,
})
mind.init(data)

4. Use Cases

4.1 AI-Generated Mind Maps

The plaintext format is ideal for LLM generation:

// Prompt example for AI
const prompt = `
Generate a mind map in plaintext format about "Web Development".
Use this format:
- Root Topic
  - Subtopic 1
    - Detail 1.1
  - Subtopic 2
`
// Then parse the AI response
const aiResponse = await callAI(prompt)
const data = plaintextToMindElixir(aiResponse)
mind.refresh(data)

4.2 File-Based Mind Maps

Store mind maps as .txt or .md files:

// Load from file
const response = await fetch('/mindmaps/project.txt')
const plaintext = await response.text()
const data = plaintextToMindElixir(plaintext)
mind.init(data)

4.3 Collaborative Editing

The plaintext format is merge-friendly for version control:

# Easy to diff and merge in Git
git diff mindmap.txt

5. Error Handling

Always wrap parsing in try-catch blocks:

function safeParse(plaintext: string): MindElixirData | null {
  try {
    return plaintextToMindElixir(plaintext)
  } catch (error) {
    console.error('Parse error:', error)
    // Return fallback data
    return {
      nodeData: {
        id: 'root',
        topic: 'Parse Error',
        children: []
      }
    }
  }
}

6. Best Practices

1. Consistent Indentation: Always use 2 spaces per level
2. Unique IDs: When using references, ensure IDs are unique within the document
3. Link Placement: Links can be placed anywhere, but keep them near related nodes for readability
4. Validation: Validate plaintext before parsing, especially for user input
5. Streaming: For streaming scenarios, parse incrementally and handle partial data gracefully

7. Format Specification Summary

8. TypeScript Types

import type { MindElixirData, NodeObj } from 'mind-elixir'
// Converter functions
function plaintextToMindElixir(plaintext: string): MindElixirData
function mindElixirToPlaintext(data: MindElixirData): string