markdown

XML Element Indexer

A powerful Visual Studio Code extension that provides intelligent XML element indexing with sibling counting, multiple display modes, and advanced performance optimizations for large files.

🌟 Features

🔢 Smart Sibling Indexing

• Shows element position among siblings (e.g., ▶ item 2/5)
• Parent-scoped counting for accurate context
• Configurable display of single elements (1/1)

🚀 Multiple Indexing Modes

• Full Mode: Index entire document with sibling counts
• Cursor Mode: Index only siblings of element at cursor (recommended for large files)
• Inline Mode: Show indexes only on current line (minimal performance impact)
• Range Mode: Index configurable range around cursor

⚡ Performance Optimized

• Intelligent caching system with LRU eviction
• Streaming parser for large XML files
• Automatic mode switching for files over threshold
• Real-time performance monitoring and reporting
• Debounced updates to prevent UI freezing

🎯 Virtual Root Support

• Set any element as virtual root to limit indexing scope
• Perfect for working with specific sections of large files
• Visual indicators for virtual root boundaries

🎨 Visual Enhancements

• Color-coded elements by depth
• Cursor line highlighting
• Customizable prefix symbols
• Theme-aware colors
• Progress indicators for long operations

📦 Installation

1. Open Visual Studio Code
2. Press Ctrl+P / Cmd+P to open Quick Open
3. Type ext install xml-element-indexer
4. Click Install

Or search for "XML Element Indexer" in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).

🚀 Usage

Commands

Access all commands through Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• XML Indexer: Toggle Indexing Mode - Cycle through modes
• XML Indexer: Set Full/Cursor/Inline/Range Mode - Set specific mode
• XML Indexer: Toggle XML Indexer - Enable/disable extension
• XML Indexer: Set Virtual Root at Cursor - Limit indexing to element subtree
• XML Indexer: Clear Virtual Root - Remove virtual root limitation
• XML Indexer: Refresh Index - Force re-parse current document
• XML Indexer: Show Performance Report - View performance metrics
• XML Indexer: Clear Cache - Clear all cached parsing data
• XML Indexer: Quick Actions - Show quick pick menu
• XML Indexer: Toggle Show Single Elements - Show/hide elements without siblings

Keyboard Shortcuts

• Ctrl+Shift+X Ctrl+Shift+M - Toggle indexing mode
• Ctrl+Shift+X Ctrl+Shift+R - Set virtual root at cursor
• Ctrl+Shift+X Ctrl+Shift+C - Clear virtual root
• Ctrl+Shift+X Ctrl+Shift+Q - Show quick actions
• Ctrl+Shift+X Ctrl+Shift+F - Refresh index
• Ctrl+Shift+X Ctrl+Shift+P - Show performance report

⚙️ Configuration

Access settings through VS Code Settings UI or settings.json:

Core Settings

{
  // Enable/disable the extension
  "xmlIndexer.enabled": true,
  
  // Default indexing mode
  "xmlIndexer.mode": "cursor",
  
  // Show elements that have no siblings (1/1)
  "xmlIndexer.showSingleElements": false,
  
  // Hide the [1/1] suffix for single elements
  "xmlIndexer.suppressSingleIndex": true,
  
  // Index leaf nodes (elements with no children)
  "xmlIndexer.indexLeafNodes": true,
  
  // Show only sequence numbers without tag names
  "xmlIndexer.sequenceOnly": false,
  
  // Prefix symbol for index display
  "xmlIndexer.indexPrefix": "▶ "
}
Performance Settings
json
{
  // Line count threshold for large file warnings
  "xmlIndexer.largeFileThreshold": 5000,
  
  // Delay before refreshing after document changes
  "xmlIndexer.refreshDelay": 300,
  
  // Lines before cursor in range mode
  "xmlIndexer.rangeModeBefore": 50,
  
  // Lines after cursor in range mode
  "xmlIndexer.rangeModeAfter": 150,
  
  // Enable caching
  "xmlIndexer.enableCache": true,
  
  // Maximum cached documents
  "xmlIndexer.cacheSize": 50,
  
  // Automatically switch to cursor mode for large files
  "xmlIndexer.autoSwitchMode": true
}
Display Settings
json
{
  // Color code elements by depth
  "xmlIndexer.colorByDepth": true,
  
  // Show progress indicators
  "xmlIndexer.enableProgressIndicators": true,
  
  // Show performance hints
  "xmlIndexer.showPerformanceHints": true,
  
  // Virtual root indicator symbol
  "xmlIndexer.virtualRootIndicator": "🎯 "
}
📖 Examples
Basic Sibling Indexing
xml
<!-- With showSingleElements: false (default) -->
<books>
    <book>Title 1</book>  ▶ book 1/3
    <book>Title 2</book>  ▶ book 2/3
    <book>Title 3</book>  ▶ book 3/3
    <author>Name</author> <!-- Not shown (1/1) -->
</books>

<!-- With showSingleElements: true -->
<books>
    <book>Title 1</book>  ▶ book 1/3
    <book>Title 2</book>  ▶ book 2/3
    <book>Title 3</book>  ▶ book 3/3
    <author>Name</author> ▶ author
</books>
Mode Comparison
Full Mode - Complete document indexing

text
✅ Best for: Small to medium files
⚡ Performance: May impact large files
Cursor Mode - Context-aware indexing

text
✅ Best for: Large files, focused editing
⚡ Performance: Excellent
Inline Mode - Current line only

text
✅ Best for: Minimal distraction
⚡ Performance: Optimal
Range Mode - Configurable window

text
✅ Best for: Custom workflows
⚡ Performance: Good
🔧 Advanced Features
Virtual Root
Set any element as the root for indexing:

Place cursor on desired element
Use Ctrl+Shift+X Ctrl+Shift+R
Only elements within that subtree will be indexed
Performance Monitoring
Status bar shows processing time and element count
Performance report shows detailed metrics
Automatic optimization suggestions
Show/Hide Single Elements
Control visibility of elements without siblings:

showSingleElements: false - Hide all 1/1 elements (default)
showSingleElements: true + suppressSingleIndex: true - Show as "▶ tagName"
showSingleElements: true + suppressSingleIndex: false - Show as "▶ tagName 1/1"
🐛 Troubleshooting
Indices not showing
Check extension is enabled (status bar)
Verify file is recognized as XML
Check showSingleElements setting if expecting 1/1 elements
Try clearing cache via command palette
Performance issues
Switch to cursor or inline mode
Set virtual root to limit scope
Increase refreshDelay setting
Check performance report for bottlenecks
Incorrect indices
Clear cache and refresh
Check for malformed XML
Verify virtual root settings
🎯 Tips
Large Files: Use cursor mode or set a virtual root
Navigation: Click status bar to quickly change modes
Quick Access: Use Quick Actions (Ctrl+Shift+X Ctrl+Shift+Q)
Performance: Monitor status bar icon (✅ = good, ⚠️ = slow)
📊 Status Bar
The status bar shows:

Current mode with icon (📊 Full, 🎯 Cursor, 📍 Inline, 📏 Range)
Element count
Virtual root indicator
Performance status
Click to toggle between modes!

🤝 Contributing
Found a bug or have a feature request? Please open an issue on our GitHub repository.

📄 License
This extension is licensed under the MIT License.

Enjoy productive XML editing! 🚀