# ⚡ MarkItDown Web Studio

🌐 **Live Web Application:** [https://markitdown-ui-kxyc.onrender.com/](https://markitdown-ui-kxyc.onrender.com/)

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

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

---

## 📸 Interface Preview

![Interface Preview](screenshot.png)

---

## 🔍 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](https://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:
```bash
# 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.):
```bash
pipx install "markitdown[all]"
```
Verify the installation works by running: `markitdown --help`

#### 3. Clone and Start the Server
```bash
# 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](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:
```powershell
# 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:
```powershell
# 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`.*
```powershell
# Install Microsoft MarkItDown with all features
pipx install "markitdown[all]"
```
Verify the installation works by running: `markitdown --help`

#### 3. Clone and Start the Server
```powershell
# 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](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:**
```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv pipx nodejs npm git
```

**Fedora:**
```bash
sudo dnf install -y python3 python3-pip pipx nodejs npm git
```

**Arch Linux:**
```bash
sudo pacman -S python python-pip pipx nodejs npm git
```

Configure `pipx` path (requires terminal restart after running):
```bash
pipx ensurepath
```

#### 2. Install Microsoft MarkItDown
Install the conversion engine globally with all optional feature formats (PDF, Excel, images, audio, etc.):
```bash
pipx install "markitdown[all]"
```
Verify the installation works by running: `markitdown --help`

#### 3. Clone and Start the Server
```bash
# 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](http://localhost:3000)** in your browser.

---

## 📁 Repository Structure

```text
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
├── Dockerfile          # Container configuration for 1-click cloud deployment
├── screenshot.png      # Application screenshot
├── package.json        # Dependencies & start scripts
├── .gitignore          # Git exclusion rules
└── README.md           # Documentation
```

---

## 🚀 Cloud Deployment (Docker / Render / Railway)

Because this application relies on a backend server with **Node.js + Python 3 + Microsoft MarkItDown** to parse and convert uploaded files, **GitHub Pages alone cannot host the file conversion engine** (GitHub Pages only hosts static HTML/CSS/JS without backend code execution).

However, you can deploy the full application to the cloud for free using Docker:

### Live Deployment (Render.com)
The app is live on Render: **[https://markitdown-ui-kxyc.onrender.com/](https://markitdown-ui-kxyc.onrender.com/)**

### How to Deploy Your Own Instance to Render.com:
1. Go to [Render.com](https://render.com) and sign in with GitHub.
2. Click **New +** -> **Web Service**.
3. Select your repository `shahariarovi789-ux/markitdown-ui`.
4. Set the **Language** / **Runtime** to **Docker**.
5. Click **Create Web Service**. Render will build the included `Dockerfile` automatically!

---

## 🔧 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`):
  ```bash
  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:
  ```bash
  pipx install --force "markitdown[all]"
  ```

---

## 💻 Running in the Background
To run the web interface in the background without keeping a terminal open:
```bash
nohup npm start > server.log 2>&1 &
```
To stop the background server:
```bash
kill $(lsof -t -i:3000)
```