Mimir DOCX Converter

A VS Code/Cursor extension that converts DOCX documents to JSON and HTML formats, specifically designed for pedagogical content management and educational documentation workflows.

What This Skill Does

This skill helps you understand, develop, and extend the Mimir extension, which:

Architecture Overview

**Technology Stack:**

**Extension Structure:**

```

mimir/

├── extension.js # Main extension logic

├── package.json # Extension manifest and configuration

├── README.md # User documentation (French)

├── LICENCE.md # MIT License

├── CLAUDE.md # AI assistant documentation

└── mimir-0.1.0.vsix # Packaged extension

```

Step-by-Step Instructions

Understanding the Conversion Flow

1. **Analyze the command registration pattern:**

- Three commands: `mimir.convertToHtml`, `mimir.convertToJson`, `mimir.previewHtml`

- All commands are available via right-click context menu on `.docx` files

- Registered in both `package.json` and `extension.js`

2. **Trace the execution flow:**

```

User Action → VSCode Command → exec() Python Script → Output File → User Notification

```

- File selection (right-click or command palette)

- Configuration loading (Python path, script path, image handling)

- Command execution (spawn Python process)

- Progress notification (VS Code progress API)

- Result handling (success notification or error message)

Working with Configuration

3. **User settings are managed via three options:**

- `mimir.pythonPath` (string, default: `"python"`) - Path to Python executable

- `mimir.scriptPath` (string, default: `""`) - Path to conversion script

- `mimir.saveImagesToDisk` (boolean, default: `true`) - Save images vs base64 encoding

4. **Configuration locations:**

- User Settings: `~/.config/Code/User/settings.json`

- Workspace Settings: `.vscode/settings.json`

Development Setup

5. **Clone and setup:**

```bash

git clone https://github.com/camauger/mimir.git

cd mimir

npm install

code .

```

6. **Run in development mode:**

- Press F5 to launch Extension Development Host

- Test commands on sample `.docx` files

7. **Run linter and tests:**

```bash

npm run lint # Run linter

npm run pretest # Lint before testing

npm test # Run tests

```

Understanding Code Structure

8. **The main extension file (`extension.js`) has three similar command handlers:**

- **File Selection Logic** (lines 12-32, 85-105, 157-178)

- Checks if file URI is provided

- Searches workspace for `.docx` files if not

- Shows quick pick dialog for user selection

- **Configuration Retrieval** (lines 41-44, 114-117, 193-195)

- Loads user/workspace settings

- Retrieves Python path and script path

- Determines image handling mode

- **Command Execution** (lines 48-80, 121-153, 198-242)

- Constructs shell command with proper escaping

- Shows progress notification

- Executes Python script via `child_process.exec`

- Handles success/error cases

9. **Preview mode implementation:**

- Creates temporary `.preview` directory

- Always uses base64 encoding to avoid path issues

- Renders HTML in webview panel (column 2)

- Enables scripts for interactivity

Python Script Integration

10. **The extension expects the Python script to accept:**

```bash

python <scriptPath> <docxPath> --output-dir <dir> [--save-images|--base64-images] [--html|--json]

```

- First argument: DOCX file path

- `--output-dir`: Output directory

- `--save-images`: Save images to disk

- `--base64-images`: Encode images as base64

- `--html`: Output HTML format

- `--json`: Output JSON format

Adding New Output Formats

11. **To add a new output format (e.g., XML):**

a. Register command in `package.json`:

```json

{

"command": "mimir.convertToXml",

"title": "DOCX: Convertir en XML"

}

```

b. Add menu item for `.docx` files:

```json

{

"when": "resourceExtname == .docx",

"command": "mimir.convertToXml",

"group": "mimir"

}

```

c. Implement command handler in `extension.js`:

```javascript

let convertToXml = vscode.commands.registerCommand(

'mimir.convertToXml',

async (fileUri) => {

// Similar logic to convertToHtml/convertToJson

// Add --xml flag to Python command

}

);

context.subscriptions.push(convertToXml);

```

Building and Packaging

12. **To package the extension:**

```bash

vsce package

```

This creates a `.vsix` file for manual installation or marketplace publishing.

Known Issues & Limitations

**Current Limitations:**

1. **No Python Script Included** - Extension requires external Python script with specific CLI interface

2. **Limited Error Context** - Generic error messages without detailed script output validation

3. **No Input Validation** - Doesn't verify Python/script paths exist before execution

4. **Synchronous Execution** - Uses `exec()` instead of `spawn()`, may have issues with large files

5. **Temporary Directory Handling** - Preview creates `.preview` folder with no automatic cleanup

**Critical Bug:**

**Security Considerations:**

Debugging

**To see detailed error output:**

1. Help → Toggle Developer Tools

2. Check Console tab for stderr output

3. Review execution commands and paths

**Common Issues:**

Repository Information

Future Enhancements

Potential improvements:

Examples

**Converting DOCX to HTML:**

1. Right-click `.docx` file in VS Code explorer

2. Select "DOCX: Convertir en HTML"

3. Extension spawns Python script with `--html` flag

4. Notification appears with "Open" button when complete

**Previewing DOCX:**

1. Right-click `.docx` file

2. Select "DOCX: Aperçu HTML"

3. HTML preview opens in webview panel (column 2)

4. Images embedded as base64

**Custom Configuration:**

```json

{

"mimir.pythonPath": "/usr/bin/python3",

"mimir.scriptPath": "/path/to/converter/script.py",

"mimir.saveImagesToDisk": false

}

```

Constraints