Metadata-Version: 2.4
Name: markdown-viewer-app
Version: 1.1.3
Summary: Beautiful markdown viewer and renderer for CLI, CI/CD, and automated workflows
License: MIT
License-File: LICENSE
Keywords: markdown,viewer,renderer,cli,ci-cd,automation,html,mermaid,emoji
Author: Ofelia B Webb
Author-email: ofelia.b.webb@gmail.com
Requires-Python: >=3.9,<3.15
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: beautifulsoup4 (>=4.12.0,<5.0.0)
Requires-Dist: chardet (>=5.2.0,<6.0.0)
Requires-Dist: flask (>=3.1.3)
Requires-Dist: flask-cors (>=6.0.0)
Requires-Dist: flask-wtf (>=1.2.0,<2.0.0)
Requires-Dist: greenlet (>=3.2.0)
Requires-Dist: lxml (>=6.0.0)
Requires-Dist: markdown (>=3.8.1)
Requires-Dist: marshmallow (>=3.26.2)
Requires-Dist: pillow (>=11.0.0,<12.0.0) ; python_version == "3.9"
Requires-Dist: pillow (>=12.1.1) ; python_version >= "3.10"
Requires-Dist: playwright (>=1.40.0,<2.0.0)
Requires-Dist: pygments (>=2.20.0)
Requires-Dist: pymdown-extensions (>=10.16.1)
Requires-Dist: python-docx (>=0.8.11,<0.9.0)
Requires-Dist: python-markdown-math (>=0.8,<0.9)
Requires-Dist: urllib3 (>=2.6.3)
Requires-Dist: werkzeug (>=3.1.6)
Project-URL: Documentation, https://github.com/dimpletz/markdown-viewer#readme
Project-URL: Homepage, https://github.com/dimpletz/markdown-viewer
Project-URL: Repository, https://github.com/dimpletz/markdown-viewer
Description-Content-Type: text/markdown

# Markdown Viewer

<div align="center" markdown="1">

**View, export, and translate markdown files — straight from the terminal**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-markdown--viewer--app-orange)](https://pypi.org/project/markdown-viewer-app/) [![Security](https://img.shields.io/badge/Security-Hardened-green)](SECURITY.md)

</div>

Open any markdown file in a full browser UI with one command. Supports PDF and Word export, Mermaid diagrams, math equations, syntax highlighting, and content translation.

---

## 📦 Installation

```bash
pip install markdown-viewer-app
playwright install chromium
```

> `playwright install chromium` is a **one-time setup** (~140 MB) required for PDF export. Skip it if you don't need PDF export.

---

## 🚀 Quick Start

```bash
# Open a file in your browser
mdview README.md

# Export to PDF
mdview README.md --export-pdf

# Export to Word
mdview README.md --export-word

# Export to both at once
mdview README.md --export-pdf --export-word

# Render to HTML only (no browser — useful for CI/CD)
mdview README.md --no-browser

# Save HTML to a specific file
mdview README.md -o output.html

# Use a custom port (default is 5000)
mdview README.md -p 5001

# Stop the background server on a custom port
mdview --stop -p 5001
```

When you run `mdview <file>`, the app:
1. Starts a background server on port 5000 (silently — no extra window opens)
2. Opens your browser directly to the rendered file
3. Returns you to the terminal immediately

The server keeps running in the background. Subsequent `mdview` calls reuse it instantly. Use `-p`/`--port` to run multiple servers on different ports simultaneously.

---

## 🖥️ CLI Reference

```
mdview [file] [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `file` | Path to the markdown file to render (optional — prompts interactively if omitted in a terminal) |

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output <path>` | *(temp file)* | Save rendered HTML to this path instead of a temporary file |
| `--no-browser` | off | Render without opening a browser window |
| `--keep` | off | Keep the HTML output file after rendering (saved as `<filename>.html` next to the source) |
| `--export-pdf [path]` | — | Export to PDF; optionally specify an output path |
| `--export-word [path]` | — | Export to Word (`.docx`); optionally specify an output path |
| `--share-pdf` | — | Export to PDF and open your email client with it attached |
| `--share-word` | — | Export to Word and open your email client with it attached |
| `-p`, `--port <port>` | `5000` | Port for the background Flask server |
| `--stop` | — | Stop the background server and release the port |
| `--version` | — | Print the installed version and exit |

### Examples

```bash
# --- Viewing ---
mdview README.md                        # Open in browser (default)
mdview README.md --no-browser           # Render without opening browser
mdview README.md --no-browser --keep    # Render and save README.html next to the source

# --- HTML output ---
mdview README.md -o docs/out.html           # Save rendered HTML to a specific path
mdview README.md --no-browser -o out.html   # Save HTML, no browser

# --- PDF export ---
mdview README.md --export-pdf               # Export to README.pdf (same directory)
mdview README.md --export-pdf ~/docs/out.pdf  # Export to a specific path

# --- Word export ---
mdview README.md --export-word              # Export to README.docx
mdview README.md --export-word ~/docs/out.docx

# --- Export both at once ---
mdview README.md --export-pdf --export-word

# --- Email sharing ---
mdview README.md --share-pdf   # Export PDF and open email client
mdview README.md --share-word  # Export Word and open email client

# --- Server / port management ---
mdview README.md -p 5001       # Open using a custom port
mdview --stop                  # Stop the default server (port 5000)
mdview --stop -p 5001          # Stop a server on a custom port

# --- CI/CD (non-interactive) ---
# When stdout is not a TTY, browser and server are skipped automatically
mdview README.md -o output.html

# --- Version ---
mdview --version
```

---

## ✨ Features

### 📝 Rich Markdown Rendering
- Full GitHub Flavored Markdown (GFM) support
- Syntax highlighting for 180+ programming languages
- Tables, task lists, footnotes, blockquotes, and more
- Emoji support with correct Unicode rendering

### 📊 Diagram Support
- **Mermaid**: flowcharts, sequence diagrams, pie charts, Gantt charts, state diagrams
- Diagrams are preserved in all export formats

### 🔢 Math Equations
- KaTeX integration for beautiful math rendering
- Inline: `$E = mc^2$`
- Block equations with full LaTeX syntax

### 📄 Export
- **PDF** — high-quality, print-ready (powered by Playwright/Chromium)
- **Word (.docx)** — editable documents with preserved formatting
- Silent: no popup dialogs, status bar updates on completion

### 🌐 Translation
- Translate content to 15+ languages directly from the UI
- Preserves markdown formatting and code blocks
- Powered by [MyMemory](https://mymemory.translated.net/) (free API, no key needed)

### 🔒 Security
- CSRF protection on all API endpoints
- Content Security Policy (CSP) headers
- Input validation with Marshmallow schemas
- Path traversal protection
- Localhost-only server binding (127.0.0.1)

### 🛠️ Productivity Tools
- Copy all content with one click
- Share via email
- Keyboard shortcuts: `Ctrl+O` (open), `Ctrl+Shift+C` (copy), `F5` (refresh), `F11` (fullscreen)

---

## 📖 Markdown Reference

### Basic Formatting

```markdown
# Heading 1
## Heading 2
### Heading 3

**bold**, *italic*, ~~strikethrough~~, ==highlighted==

- Unordered list
  - Nested item

1. Ordered list

[Link text](https://example.com)
![Alt text](https://example.com/image.png)
```

### Code Blocks

````markdown
```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

```sql
SELECT name, COUNT(*) FROM users GROUP BY name;
```
````

### Tables

```markdown
| Feature        | Markdown Viewer | Typora | VS Code |
|----------------|:---------------:|:------:|:-------:|
| PDF Export     | ✅              | ✅     | ❌      |
| Word Export    | ✅              | ✅     | ❌      |
| Translation    | ✅              | ❌     | ❌      |
| Diagrams       | ✅              | ✅     | ✅      |
| Free & Open    | ✅              | ❌     | ✅      |
```

### Mermaid Diagrams

````markdown
```mermaid
graph TD
    A[Start] --> B{Working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug] --> B
```

```mermaid
sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response
```
````

### Math Equations

```markdown
Inline: $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$

Block:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

### Task Lists

```markdown
- [x] Install Markdown Viewer
- [x] Open first document
- [ ] Try exporting to PDF
```

---

## 🔧 Development Setup

```bash
git clone https://github.com/dimpletz/markdown-viewer.git
cd markdown-viewer
poetry install
poetry run playwright install chromium
```

### Run

```bash
# Open a file (server auto-reloads on code changes)
poetry run mdview README.md

# Or start the server standalone
poetry run mdview README.md --no-browser
```

### Tests

```bash
# Run all tests
poetry run pytest

# With coverage report
poetry run pytest --cov=markdown_viewer --cov-report=html
```

### Project Structure

```
markdown-viewer/
├── markdown_viewer/
│   ├── app.py                # Flask application factory
│   ├── routes.py             # API endpoints
│   ├── server.py             # Server management
│   ├── cli.py                # CLI entry point (mdview)
│   ├── electron/             # Browser UI (HTML/JS/CSS)
│   │   └── renderer/
│   │       ├── index.html
│   │       ├── scripts/
│   │       └── styles/
│   ├── exporters/            # PDF & Word export
│   ├── processors/           # Markdown processing
│   ├── translators/          # Translation service
│   └── utils/                # File handling
├── tests/
├── docs/
└── examples/
```

---

## 🐛 Known Limitations

- PDF export requires `playwright install chromium` (one-time ~140 MB download)
- Translation requires an internet connection
- Word export has limited support for complex CSS styling

---

## 📚 More Documentation

- [CLI Usage & Export Examples](docs/CLI_USAGE.md)
- [Export Features](docs/EXPORT_FEATURES.md)
- [Installation Guide](docs/INSTALLATION.md)
- [Security Policy](SECURITY.md)
- [Changelog](CHANGELOG.md)

---

## 🤝 Contributing

1. Fork the repository
2. Create a branch: `git checkout -b feature/my-feature`
3. Make your changes and add tests: `poetry run pytest`
4. Open a pull request

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **[Flask](https://flask.palletsprojects.com/)** — Python web framework
- **[Python-Markdown](https://python-markdown.github.io/)** — Markdown parser
- **[Playwright](https://playwright.dev/)** — PDF generation via Chromium
- **[python-docx](https://python-docx.readthedocs.io/)** — Word document export
- **[Mermaid](https://mermaid.js.org/)** — Diagram rendering
- **[KaTeX](https://katex.org/)** — Math typesetting
- **[Pygments](https://pygments.org/)** — Syntax highlighting
- **[DOMPurify](https://github.com/cure53/DOMPurify)** — XSS sanitization
- **[MyMemory](https://mymemory.translated.net/)** — Free translation API (called directly via stdlib `urllib`)

