markdown-viewer-app 1.1.3

Beautiful markdown viewer and renderer for CLI, CI/CD, and automated workflows

Markdown Viewer

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

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

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

# 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

# --- 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 (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

# 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

```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

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

Mermaid Diagrams

```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

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

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

Task Lists

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

---

🔧 Development Setup

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

Run

# 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

# 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
• Export Features
• Installation Guide
• Security Policy
• Changelog

---

🤝 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 for details.

---

🙏 Acknowledgments

• Flask — Python web framework
• Python-Markdown — Markdown parser
• Playwright — PDF generation via Chromium
• python-docx — Word document export
• Mermaid — Diagram rendering
• KaTeX — Math typesetting
• Pygments — Syntax highlighting
• DOMPurify — XSS sanitization
• MyMemory — Free translation API (called directly via stdlib urllib)