README.md

---
title: Mermaid Diagram Renderer
emoji: 🧜‍♀️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
---

# 🧜‍♀️ Mermaid Diagram Renderer

A simple web application for rendering [Mermaid](https://mermaid.js.org/) diagrams using Gradio, designed for deployment on Hugging Face Spaces.

## Features

- Web-based interface for entering Mermaid code
- Multiple output formats: PNG, SVG, PDF  
- Theme selection: Default, Forest, Dark, Neutral
- Easy file download of generated diagrams
- Built with Gradio for seamless Hugging Face Spaces deployment

## Deploy to Hugging Face Spaces

1. **Create a new Space** on [Hugging Face Spaces](https://huggingface.co/spaces)
2. **Choose SDK**: Select "Gradio" 
3. **Upload files**: Copy these files to your Space:
   - `app.py`
   - `mermaid_renderer.py` 
   - `requirements.txt`
4. **Your Space will automatically build and deploy!**

The app will be available at `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

## Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Install Node.js and mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# Run the app
python app.py
```

## Dependencies

- **Python**: Gradio for the web interface
- **Node.js**: Required for @mermaid-js/mermaid-cli
- **mermaid-cli**: Handles the actual diagram rendering

*Note: Hugging Face Spaces handles Node.js and mermaid-cli installation automatically.*

---

## Local Testing

To test this project locally before deploying or pushing to Hugging Face Spaces, follow these steps:

1. **Create and activate a Python virtual environment**

   On macOS/Linux:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```

   On Windows:
   ```cmd
   python -m venv venv
   venv\Scripts\activate
   ```

2. **Upgrade pip (recommended)**
   ```bash
   pip install --upgrade pip
   ```

3. **Install Python dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Ensure Node.js is installed**
   ```bash
   node --version
   ```
   If not installed, download from [nodejs.org](https://nodejs.org/).

5. **Ensure @mermaid-js/mermaid-cli is installed globally**
   ```bash
   npm install -g @mermaid-js/mermaid-cli@9.0.0
   ```

6. **Run the Gradio app**
   ```bash
   python app.py
   ```
   Gradio will print a local URL (e.g., http://127.0.0.1:7860/) in the terminal.

7. **Open the app in your browser**
   Visit the local URL to interact with and test the interface.

When finished, you can deactivate the virtual environment with:
```bash
deactivate
```

**Note:**  
If you accidentally added the `venv` folder to git, remove it from tracking with:
```bash
git rm -r --cached venv
git commit -m "Stop tracking venv directory"
```