⚡ Cyberpunk MarkItDown Document Converter & GUI

A high-contrast, retro-futuristic local web interface for converting complex documents (PDFs, Word documents, Excel sheets, presentations, audio recordings, images, and HTML) into clean, structured Markdown.

This local tool provides a graphical user interface (GUI) wrapper on top of Microsoft's official MarkItDown Python library.

📸 Interface Preview

Related MCP server: flexberry-markitdown-mcp

🔍 Core Technology Disclosure

This project is a wrapper interface and does not compile documents from scratch. It relies directly on:

• Microsoft MarkItDown: The core document conversion engine. Visit their repository at github.com/microsoft/markitdown for more details.

• Model Context Protocol (MCP) Compatible: The same core parser running this interface is also configured as an MCP server for AI clients (like Claude Desktop).

🛠 Features

• Visual Design: Immersive neon cyber-terminal styled with retro CRT scanline grids, glitch logo, and glowing interactive elements.

• Interactive Audio: Real-time feedback sounds (beeps, success chimes, error hums) generated on-the-fly using the Web Audio API (no external audio assets required).

• Live Diagnostic Feed: Real-time log console showing exactly what files are loaded, processed, and deleted.

• Multi-Format Extraction: Seamlessly translates text and structural data from PDF, DOCX, XLSX, PPTX, HTML, CSV, PNG/JPG, and Audio (Speech-to-Text).

⚙️ Step-by-Step Installation Guide

To get this app running on your computer, follow these simple steps:

⚙️ Installation & Setup

Choose your operating system to set up and run the decompiler:

🍎 macOS Installation Guide

1. Install System Dependencies

We use Homebrew to manage command-line installations cleanly. Open your terminal and run:

# Install Homebrew (if you don't have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3, pipx, and Node.js
brew install python pipx node

# Configure pipx path (requires terminal restart after running)
pipx ensurepath

2. Install Microsoft MarkItDown

Install the conversion engine globally with all optional feature formats (PDF, Excel, images, audio, etc.):

pipx install "markitdown[all]"

Verify the installation works by running: markitdown --help

3. Clone and Start the Server

# Clone the repository
git clone https://github.com/shahariarovi789-ux/markitdown-ui.git
cd markitdown-ui

# Install dependencies
npm install

# Start the server
npm start

Open http://localhost:3000 in your browser.

🪟 Windows Installation Guide

1. Install System Dependencies

We recommend using Windows Package Manager (winget) or installing manually. Open PowerShell and run:

# Install Python, Node.js, and Git
winget install -e --id Python.Python.3
winget install -e --id OpenJS.NodeJS
winget install -e --id Git.Git

Note: Make sure to restart your terminal or computer after installing these packages so the environment variables take effect.

2. Configure pipx and Install Microsoft MarkItDown

Open a new PowerShell window and run:

# Install pipx via Python pip
py -m pip install --user pipx

# Configure pipx paths
py -m pipx ensurepath

Note: Please restart your PowerShell window after running ensurepath.

# Install Microsoft MarkItDown with all features
pipx install "markitdown[all]"

Verify the installation works by running: markitdown --help

3. Clone and Start the Server

# Clone the repository
git clone https://github.com/shahariarovi789-ux/markitdown-ui.git
cd markitdown-ui

# Install dependencies
npm install

# Start the server
npm start

Open http://localhost:3000 in your browser.

🐧 Linux Installation Guide (Ubuntu / Debian / Fedora / Arch)

1. Install System Dependencies

Install Python 3, pipx, Node.js, and Git using your distribution's package manager:

Ubuntu / Debian:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv pipx nodejs npm git

Fedora:

sudo dnf install -y python3 python3-pip pipx nodejs npm git

Arch Linux:

sudo pacman -S python python-pip pipx nodejs npm git

Configure pipx path (requires terminal restart after running):

pipx ensurepath

2. Install Microsoft MarkItDown

Install the conversion engine globally with all optional feature formats (PDF, Excel, images, audio, etc.):

pipx install "markitdown[all]"

Verify the installation works by running: markitdown --help

3. Clone and Start the Server

# Clone the repository
git clone https://github.com/shahariarovi789-ux/markitdown-ui.git
cd markitdown-ui

# Install dependencies
npm install

# Start the server
npm start

Open http://localhost:3000 in your browser.

📁 Repository Structure

markitdown-ui/
├── public/
│   └── index.html      # Self-contained Cyberpunk UI frontend
├── uploads/            # Temporary directory for file conversion buffers (auto-cleaned)
├── server.js           # Express API backend server
├── screenshot.png      # Application screenshot
├── package.json        # Dependencies & start scripts
├── .gitignore          # Git exclusion rules
└── README.md           # Documentation

🔧 Troubleshooting

1. markitdown CLI command not found

If your terminal states that the command markitdown cannot be found, it means ~/.local/bin (where pipx installs command symlinks) is not in your system $PATH.

• Run pipx ensurepath again.

• If that doesn't fix it, manually add it to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.bash_profile):

  export PATH="$HOME/.local/bin:$PATH"

• Open a new terminal and try running markitdown --help.

2. Conversions fail or return empty output

Ensure that you ran pipx install "markitdown[all]" instead of just pipx install markitdown. The [all] tag installs essential parsing libraries like PyMuPDF for PDFs, openpyxl for Excel files, and others required to successfully unpack formats.

• To upgrade your existing installation, run:

  pipx install --force "markitdown[all]"

💻 Running in the Background

To run the web interface in the background without keeping a terminal open:

nohup npm start > server.log 2>&1 &

To stop the background server:

kill $(lsof -t -i:3000)