EPUB Editor for Visual Studio Code

A powerful Visual Studio Code extension that allows you to create, edit, and manage EPUB files directly within the familiar VS Code environment. Now featuring native AI integration for editorial content improvement and enhanced user experience with non-intrusive notifications. Edit your ebooks like any other project with full file system integration, syntax highlighting, auto-save functionality, and intelligent AI assistance.

✨ Features

🔔 Enhanced User Experience ⭐ NEW in v0.1.8

• 🚀 Non-Intrusive Notifications: All routine notifications now auto-dismiss without manual intervention
• ⏱️ Smart Status Bar Messages: Intelligent timing for different message types
• 📍 Seamless Workflow: Focus on writing without notification interruptions
• 🎯 Selective Modality: Only critical dialogs require user interaction
• 📂 Direct Context Menu Access: Open EPUB files directly from file explorer without additional dialogs

📚 Complete EPUB Authoring

• Create new EPUB files from scratch with guided setup
• Open existing EPUB files as virtual workspace folders
• Edit all EPUB content (XHTML, CSS, XML, images) directly in VS Code
• Auto-save functionality with automatic backup creation

🧠 AI-Powered Editorial Assistant ⭐ UPDATED in v0.1.7

• 🤖 Multiple AI Models: Choose from 7 powerful free AI models optimized for different tasks
  • Gemini 2.0 Flash Experimental (1M context) - Latest Google model, perfect for long documents
  • NVIDIA Llama 3.1 Nemotron Ultra 253B (128K context) - The largest model available (253B parameters)
  • Qwen3 235B (256K context) - Second largest model with massive context window (235B parameters)
  • DeepSeek R1 (128K context) - Excellent reasoning and advanced capabilities
  • Microsoft Phi-4 Reasoning Plus (128K context) - Specialized in complex reasoning tasks
  • Hermes 3 Llama 405B (128K context) - Ultra-powerful model with 405B parameters
  • Qwen3 8B (32K context) - Fast and efficient with excellent speed/quality balance
• 🎯 Editorial AI Functions:
  • 🧠 Text Improvement: Enhance narrative flow and literary style
  • ✏️ Grammar Correction: Fix spelling and grammar without altering style
  • 🌐 Smart Translation: Contextual translation maintaining EPUB formatting
  • 📝 Content Expansion: Add depth and detail to existing paragraphs
  • 📄 Intelligent Summarization: Create concise summaries of selected content
• 🎨 Context Menu Integration: Right-click access to all AI functions when text is selected
• ⚙️ Smart Configuration: Secure API key storage, model selection interface, language preferences
• 🔧 AI Management: Test connections, switch models, view model information

🎯 Core Capabilities

• ✅ Virtual File System: Browse EPUB contents like a regular folder
• ✅ Full Edit Support: Modify text, styles, metadata, and structure
• ✅ Auto-Save: Changes are automatically saved to the EPUB file
• ✅ Backup System: Automatic timestamped backups (keeps 5 most recent)
• ✅ Status Tracking: Track which files have been modified
• ✅ Metadata Viewer: Display and edit EPUB metadata
• ✅ UUID Generation: Automatic unique identifiers for new EPUBs

🆕 EPUB Creation Wizard

• Interactive metadata wizard (title, author, language, publisher, etc.)
• Complete EPUB 3.0 structure generation
• Basic CSS and XHTML templates included
• Automatic workspace loading after creation

🚀 Quick Start with AI

1. Setup AI Integration

# Get your free API key from OpenRouter.ai
# Configure in VS Code: Ctrl+Shift+P → "EPUB AI: Configure API Key"

2. Choose Your AI Model

# Access via Command Palette
Ctrl+Shift+P → "EPUB AI: Select AI Model"
# Choose based on your needs:
# - Gemini 2.0: Best for long documents (novels, books)
# - NVIDIA Nemotron 253B: Ultra-powerful for complex tasks
# - Qwen3 235B: Large-scale processing with massive context
# - DeepSeek R1: Advanced reasoning and analysis
# - Phi-4 Reasoning Plus: Specialized complex reasoning
# - Hermes 3 Llama 405B: Ultra-powerful processing
# - Qwen3 8B: Fast and efficient for quick tasks

3. Start Editing with AI

# Select any text in your EPUB files
# Right-click → Choose AI function:
# 🧠 Improve text style and flow
# ✏️ Fix grammar and spelling
# 🌐 Translate to another language
# 📝 Expand with more detail
# 📄 Summarize content

🔔 Non-Intrusive Workflow ⭐ NEW in v0.1.8

Experience seamless EPUB editing with our enhanced notification system:

• 🚀 Auto-Dismissing Messages: All routine notifications disappear automatically
• ⏱️ Smart Timing: Different timeouts for different message types
• 📍 Status Bar Integration: Key information shown in status bar without blocking workflow
• 🎯 Focus on Writing: No more manual dismissal of routine confirmations

Example Workflow:

1. Open EPUB → Brief loading message in status bar (2s)
2. Edit content → Seamless editing without interruptions
3. Save changes → Quick confirmation in status bar (3s)
4. Continue writing → Uninterrupted creative flow

📖 Complete Guide: See AI-USER-GUIDE.md for detailed setup and usage instructions

🚧 Pending Features

📋 Roadmap v0.2.0 - In Development

🎨 UX Improvements

• [ ] Real-time Preview: EPUB rendered visualization within VS Code
• [ ] Breadcrumb Navigation: Hierarchical navigation through EPUB structure
• [ ] Structure Panel: Tree view with all chapters and sections
• [ ] Custom Themes: EPUB-specific editing themes

✏️ Advanced Metadata Editor

• [ ] Graphical Editor: Visual interface for editing metadata without touching XML
• [ ] Author Management: Add/edit multiple authors with roles
• [ ] Custom Fields: Support for publisher-specific metadata
• [ ] Real-time Validation: Automatic verification of required metadata

🔍 Validation and Verification

• [ ] Complete EPUB Validator: Integration with epubcheck
• [ ] Link Verification: Detect broken internal and external links
• [ ] Image Validation: Verify all images exist and have valid formats
• [ ] Accessibility Analysis: Check compliance with accessibility standards

🎬 Advanced Content Management

• [ ] Reorder Chapters: Drag and drop to reorganize structure
• [ ] Add/Remove Files: Complete file management from the interface
• [ ] Image Optimization: Automatic image compression
• [ ] Style Management: Visual CSS editor with preview

📤 Import and Export

• [ ] Export to PDF: Direct EPUB to PDF conversion
• [ ] Export to MOBI: Kindle device compatibility
• [ ] Import from Word: Convert .docx documents to EPUB
• [ ] Import from Markdown: Convert .md files to EPUB structure

🧠 Roadmap v0.2.5 - AI Content Assistant Integration ⭐

🎯 The Key Differentiator: Sprint focused exclusively on AI to get early user feedback

🤖 Native AI Assistant

• [X] Python-TypeScript Bridge: Communication with OpenRouter backend for AI processing
• [X] Contextual AI Commands: Right-click menu with text improvement, correction and translation options
• [ ] AI Chat Panel: Side view for personalized conversations with the assistant
• [X] Secure Configuration: OpenRouter API Key management in VS Code Settings

✨ Editorial-Specific AI Features

• [X] Improve text with AI: Suggest narrative flow and style improvements
• [X] Grammar and spelling correction: Intelligent context-aware error analysis
• [X] Text translation: Contextual translation preserving EPUB format
• [X] Specialized prompts: Templates specific for authors and editors

📋 Complete details: See ROADMAP-v0.2.5-AI.md

🔮 Roadmap v0.3.0 - Advanced Features

📚 Templates and Automation

• [ ] Predefined Templates: Templates for different book types (novel, technical manual, etc.)
• [ ] Chapter Assistant: Automatic generation of new chapters with structure
• [ ] Automatic Index: Automatic generation of indexes and table of contents
• [ ] Automatic Numbering: Automatic chapter and page numbering

🎵 Multimedia and Rich Content

• [ ] Audio Support: Audio file integration for audiobooks
• [ ] Video Support: Multimedia content embedding
• [ ] Interactive Annotations: Interactive footnotes
• [ ] Dynamic Glossary: Automatic term and definition management

🛠️ Author Tools

• [ ] Spell Check: Integration with spell checkers in multiple languages
• [ ] Document Statistics: Word count, characters, estimated reading time
• [ ] Integrated Version Control: EPUB-specific change history
• [ ] Real-time Collaboration: Collaborative editing with other authors/editors

🔌 Integrations

• [ ] GitHub Integration: Automatic synchronization with repositories
• [ ] Publishing Service Integration: Direct connection with publishing platforms
• [ ] Extension API: Allow other extensions to interact with EPUB Editor
• [ ] Custom Plugins: Plugin system for specific functionalities

💡 Have Ideas?

Is there any functionality you'd like to see implemented?

• 📧 Contact us through GitHub Issues
• 🗳️ Vote for the most important features
• 🤝 Contribute to project development

📊 Current Status

• ✅ Basic Features: 100% implemented
• 🔶 v0.2.0: 50% completed
• 🧠 v0.2.5 (AI): Completed - The key differentiator
• ⏳ v0.3.0: In planning

🚀 Quick Start

Installation

Option 1: VS Code Marketplace ⭐ RECOMMENDED

1. From VS Code Extensions view:

   • Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)
   • Search for "EPUB Editor"
   • Click Install on the extension by Pishu

2. From Command Line:

   code --install-extension pishu.epub-editor
   

3. From VS Code Marketplace:

   • Visit: https://marketplace.visualstudio.com/items?itemName=pishu.epub-editor
   • Click Install

Option 2: Manual Installation (Advanced users)

1. From GitHub Releases:

   • Download latest .vsix from Releases
   • Install: code --install-extension epub-editor-0.1.8.vsix

2. From source:

   git clone https://github.com/robermad1986/epub-editor-vscode.git
   cd epub-editor-vscode
   npm install
   npm run compile
   npm run package
   code --install-extension epub-editor-0.1.8.vsix
   

Usage

Creating a New EPUB

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "EPUB: Create New EPUB"
3. Follow the metadata wizard:
   • Enter book title and author (required)
   • Select language and add optional details
   • Choose save location
4. The new EPUB loads automatically in your workspace

Opening an Existing EPUB

1. Right-click on any .epub file in VS Code Explorer
2. Select "Open as Virtual Folder"
3. The EPUB structure appears as a workspace folder
4. Edit any file directly - changes auto-save to the EPUB

📖 Complete Usage Guide

🆕 How to Create a New EPUB

Step by Step:

1. Start Creation:

   • Open Command Palette: Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
   • Type: "EPUB: Create New EPUB" and select the command
   • The command is available at any time, you don't need to have an EPUB open

2. Metadata Wizard (Interactive):

   • 📚 Title (required): Enter the book title (e.g.: "My Great Novel")
   • ✍️ Author (required): Author name (e.g.: "John Doe")
   • 🌍 Language: Select from predefined list or enter custom code
     • Options: English (en), Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt)
     • Or select "Other..." to enter codes like ja, zh, ru, etc.
   • 🏢 Publisher (optional): Publishing house name
   • 📝 Description (optional): Book summary
   • 🏷️ Category/Genre (optional): Fiction, Non-Fiction, Biography, etc.
   • ©️ Rights (optional): Copyright information

3. Save the File:

   • Select location and filename for the .epub file
   • File is automatically suggested with the book title
   • Progress bar is shown during creation

4. Result:

   📖 MyBook.epub
   ├── 📄 mimetype (application/epub+zip)
   ├── 📁 META-INF/
   │   └── 📄 container.xml (configuration)
   └── 📁 OEBPS/
       ├── 📄 content.opf (book metadata)
       ├── 📄 toc.ncx (table of contents)
       ├── 📁 Text/
       │   ├── 📄 title.xhtml (title page)
       │   └── 📄 chapter1.xhtml (first chapter)
       └── 📁 Styles/
           └── 📄 style.css (basic styles)
   

5. Automatic Loading:

   • The new EPUB automatically opens in your workspace
   • You can immediately start editing the files

💾 How to Save an EPUB

Automatic Save System:

• 🔄 Smart Auto-save: Changes are automatically saved when pressing Ctrl+S (Cmd+S on Mac) on any file
• 📋 Change Tracking: The system tracks which files have been modified
• 🛡️ Automatic Backups: Timestamped backup copies are created before each save

Save Methods:

1. Quick Save (Recommended):

   • Shortcut: Ctrl+Shift+S (Windows/Linux) or Cmd+Shift+S (Mac)
   • Command: "EPUB: Save EPUB File" from Command Palette
   • Saves all pending changes instantly

2. Save with Confirmation:

   • Command: "EPUB: Save EPUB File (with confirmation)"
   • Shows dialog with number of modified files
   • Allows cancellation before confirming save

3. Individual Auto-save:

   • When editing any file and saving with Ctrl+S, auto-save is triggered
   • Shows notification: "📚 EPUB saved" in status bar

Backup System:

• 📁 Location: Same folder as original EPUB
• 🕒 Format: BookName.epub.backup.1686234567890
• 📊 Management: Automatically keeps the 5 most recent copies
• 🗑️ Cleanup: Old backups are automatically deleted

Check Save Status:

• Command: "EPUB: EPUB Status"
• Shortcut: Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (Mac)
• Information shown:
  • 📁 Total files in EPUB
  • ✏️ Number of modified files
  • 💾 General status (saved / pending changes)

✅ How to Validate an EPUB

State and Modification Verification:

1. General EPUB Status:

   • Command: "EPUB: EPUB Status"
   • Shortcut: Ctrl+Shift+I / Cmd+Shift+I
   • Shows:
     • Total number of files
     • Modified unsaved files
     • Synchronization status

2. List Modified Files:

   • Command: "EPUB: List Modified Files"
   • Functionality: Detailed list of all files with pending changes
   • Useful for: Reviewing what needs to be saved before closing

3. EPUB Metadata:

   • Command: "EPUB: Show EPUB Metadata"
   • Information shown:
     • 📚 Book title
     • ✍️ Author
     • 🌍 Language
     • 🏢 Publisher
     • 🆔 Unique identifier (UUID)

Visual Validation Indicators:

1. Status Bar:

   • 📊 Modified files counter: "📚 EPUB: 3 files modified"
   • 💾 Save confirmation: "📚 EPUB saved"
   • ⚠️ Alerts if there are problems

2. File Explorer:

   • Modified files appear visually marked
   • Hierarchical structure shows EPUB organization

3. System Notifications:

   • ✅ Confirmation when saved successfully
   • 📝 Progress during save operations
   • ⚠️ Errors if something fails

Basic Structure Validation:

The system automatically verifies:

• ✅ mimetype: Must contain "application/epub+zip"
• ✅ META-INF/container.xml: Valid configuration file
• ✅ content.opf: Complete metadata and manifest
• ✅ XHTML files: Correct syntax
• ✅ CSS links: Valid style references

Manual Validation Process:

1. Before Publishing:

   1. Run: "EPUB: EPUB Status" → Verify 0 modified files
   2. Run: "EPUB: Show EPUB Metadata" → Review information
   3. Open key files (content.opf, toc.ncx) → Verify structure
   4. Test chapter links → Functional navigation
   

2. Content Verification:

   • 📄 Review that all chapters are present
   • 🎨 Verify CSS styles apply correctly
   • 🖼️ Check that images load (if any)
   • 🔗 Test navigation in table of contents

🔧 Recommended Workflow

For Authors (Creating from Scratch):

1. "EPUB: Create New EPUB" → Create initial structure
2. Edit title.xhtml → Customize title page
3. Edit chapter1.xhtml → Write first chapter
4. Create additional chapters → Duplicate and modify chapter1.xhtml
5. Update content.opf and toc.ncx → Add new chapters to manifest
6. Ctrl+Shift+S → Save regularly
7. "EPUB: EPUB Status" → Verify before distribution

For Editors (Modifying Existing EPUBs):

1. Right-click on file.epub → "Open as Virtual Folder"
2. "EPUB: Show EPUB Metadata" → Review current information
3. Edit necessary files → Make corrections
4. "EPUB: List Modified Files" → Verify changes
5. Ctrl+Shift+S → Save changes
6. Verify automatic backup → Additional security

Essential Keyboard Shortcuts:

• Ctrl+Shift+P (Cmd+Shift+P) → Command Palette
• Ctrl+Shift+S (Cmd+Shift+S) → Save EPUB
• Ctrl+Shift+I (Cmd+Shift+I) → EPUB Status
• Ctrl+S (Cmd+S) → Save individual file (triggers auto-save)

---

💡 Pro Tip: Use auto-save frequently during editing and check status before closing VS Code to ensure all your changes are preserved.

🎮 Commands

📚 Core EPUB Commands

Command	Description	Shortcut
EPUB: Create New EPUB	Create a new EPUB file from scratch	-
EPUB: Open as Virtual Folder	Open EPUB as workspace folder	Right-click context menu
EPUB: Save EPUB File	Save all changes to EPUB	Ctrl+Shift+S
EPUB: EPUB Status	Show modification status	Ctrl+Shift+I
EPUB: Show EPUB Metadata	Display book metadata	-
EPUB: List Modified Files	Show files with unsaved changes	-
EPUB: Close EPUB File	Close EPUB workspace	-
EPUB: Refresh EPUB	Refresh file explorer	-

🧠 AI-Powered Commands ⭐ UPDATED in v0.1.7

AI Setup & Configuration

Command	Description	Icon
EPUB AI: Configure API Key	Set up OpenRouter API key securely	🔑
EPUB AI: Test AI Connection	Verify API connection and model access	🧪
EPUB AI: Select AI Model	Choose from 5 available AI models	🤖
EPUB AI: Model Information	View current model details and capabilities	ℹ️

AI Editorial Functions (Available via Right-Click on Selected Text)

Function	Description	Use Case	Icon
Improve Text with AI	Enhance narrative flow and literary style	Polish paragraphs, improve expression	🧠
Grammar & Spelling Correction	Fix errors without changing style	Final manuscript review	✏️
Translate Text	Contextual translation maintaining EPUB format	Book localization	🌐
Expand Paragraph	Add depth and detail to content	Enrich descriptions, add context	📝
Summarize Text	Create concise summaries	Chapter summaries, synopses	📄

AI Model Options

Model	Context Size	Best For	Free
Gemini 2.0 Flash Experimental	1M tokens	Long documents, novels	✅
NVIDIA Llama 3.1 Nemotron Ultra 253B	128K tokens	Ultra-complex tasks (253B parameters)	✅
Qwen3 235B	256K tokens	Large-scale processing (235B parameters)	✅
DeepSeek R1	128K tokens	Advanced reasoning and analysis	✅
Microsoft Phi-4 Reasoning Plus	128K tokens	Complex reasoning tasks	✅
Hermes 3 Llama 405B	128K tokens	Ultra-powerful processing (405B parameters)	✅
Qwen3 8B	32K tokens	Fast processing with quality balance	✅

📁 Supported EPUB Structure

The extension supports full EPUB 3.0 structure:

📖 MyBook.epub
├── 📄 mimetype
├── 📁 META-INF/
│   └── 📄 container.xml
└── 📁 OEBPS/
    ├── 📄 content.opf        # Package metadata
    ├── 📄 toc.ncx           # Navigation
    ├── 📁 Text/             # XHTML content
    │   ├── 📄 title.xhtml
    │   ├── 📄 chapter1.xhtml
    │   └── 📄 ...
    ├── 📁 Styles/           # CSS stylesheets
    │   └── 📄 style.css
    └── 📁 Images/           # Images and media
        └── 📄 cover.jpg

💡 Use Cases

✍️ Authors & Writers

• Write and edit your ebook chapters in VS Code
• Use familiar editor features (IntelliSense, extensions, themes)
• AI-powered writing assistance for improving text quality
• Version control your ebook with Git
• Collaborate with editors using VS Code Live Share

📚 Publishers & Editors

• Edit existing EPUB files for corrections or updates
• AI-powered editorial workflow with grammar correction and text improvement
• Maintain consistent formatting across multiple books
• Multi-language support with AI translation capabilities
• Quality assurance with syntax highlighting and error detection

🛠️ Developers & Designers

• Customize EPUB CSS and styling
• Add interactive features to enhanced EPUBs
• Debug EPUB structure and metadata
• Automate EPUB processing workflows

🔧 Technical Details

Built With

• TypeScript - Type-safe development
• JSZip - EPUB file manipulation
• UUID - Unique identifier generation
• VS Code API - Deep editor integration
• Python 3.7+ - AI backend processing
• OpenRouter API - Multi-model AI access

AI Integration Architecture

• 🐍 Python Backend: OpenRouter client with support for 5 AI models
• 🔗 TypeScript Bridge: Seamless communication between VS Code and Python
• 📊 Progress Indicators: Real-time feedback during AI operations
• ⏱️ Timeout Management: 60-second timeout with proper cleanup
• 🛡️ Error Handling: Comprehensive error management for API calls
• 🔒 Secure Storage: API keys stored securely in VS Code settings

File System Provider

The extension implements a custom FileSystemProvider that:

• Mounts EPUB files as virtual directories
• Provides seamless read/write operations
• Maintains file modification tracking
• Handles automatic backup creation
• Integrates with AI processing pipeline

Supported File Types

• ✅ XHTML - Book content with syntax highlighting and AI enhancement
• ✅ CSS - Stylesheets with IntelliSense
• ✅ XML - Metadata and navigation files
• ✅ Images - JPG, PNG, SVG preview and editing
• ✅ Fonts - Custom font file management

AI Model Requirements

• Python 3.7+ installed on your system
• OpenRouter account with API access (free tier available)
• Internet connection for AI model access
• VS Code 1.80.0+ for full compatibility

🔄 Installation & Updates

Installing from VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for: EPUB Editor
4. Click Install on the extension by Pishu

Installing from VSIX (Alternative)

# Download the latest VSIX file from GitHub releases
code --install-extension epub-editor-0.1.8.vsix

Setting up AI Features

# 1. Ensure Python 3.7+ is installed
python3 --version

# 2. Get free API key from OpenRouter.ai
# 3. Configure in VS Code:
#    - Open Command Palette (Ctrl+Shift+P)
#    - Run "EPUB AI: Configure API Key"
#    - Test connection with "EPUB AI: Test AI Connection"

Building from Source

git clone <repository-url>
cd epub-vscode-extension
npm install
npm run compile
npm run package
code --install-extension epub-editor-0.1.7.vsix

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone <repository-url>
cd epub-vscode-extension
npm install
npm run watch    # Compile in watch mode
F5               # Launch Extension Development Host

AI Development

# Install Python dependencies
cd src/python
pip install -r requirements.txt

# Test AI functionality
python3 openrouter_client.py --help

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔄 Changelog

See CHANGELOG.md for a detailed history of changes.

📖 Documentation

• AI User Guide - Complete setup and usage guide for AI features
• AI Roadmap - Detailed AI development roadmap
• Changelog - Version history and updates

🐛 Issues & Support

If you encounter any issues or have feature requests, please:

1. Check existing issues on GitHub
2. For AI-related issues: Include Python version, OS, and error messages
3. Create a new issue with detailed description
4. Include VS Code version and extension version

Common AI Issues

• API Key errors: Verify your OpenRouter API key is valid
• Python not found: Ensure Python 3.7+ is installed and accessible
• Timeout errors: Check internet connection and try smaller text selections
• Model selection: Use "EPUB AI: Select AI Model" to switch models

---

Made with ❤️ for the ebook authoring community

🧠 Powered by AI for next-generation content creation