Metadata-Version: 2.4
Name: innomd
Version: 0.3.0
Summary: Terminal Markdown viewer with LaTeX math, Jupyter notebooks, live reload, and themes.
Author-email: Ivan Maradzhiyski <ivan.maradzhiyski@innomatica.de>
Maintainer-email: Innomatica GmbH <ivan.maradzhiyski@innomatica.de>
License: MIT License
        
        Copyright (c) 2026 Innomatica GmbH
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Innomatica-GmbH/innomd
Project-URL: Repository, https://github.com/Innomatica-GmbH/innomd
Project-URL: Issues, https://github.com/Innomatica-GmbH/innomd/issues
Project-URL: Changelog, https://github.com/Innomatica-GmbH/innomd/releases
Project-URL: Organization, https://innomatica.de
Keywords: markdown,latex,math,terminal,cli,viewer,jupyter,ipynb,live-reload,pager,rich
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
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: Topic :: Documentation
Classifier: Topic :: Terminals
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Dynamic: license-file

<p align="center">
  <img src="assets/innomd-mark-512.png" alt="innomd" width="120">
</p>

<h1 align="center">innomd — Terminal Markdown Viewer with LaTeX Math Support</h1>

<p align="center">
  <em>Render Markdown files with real LaTeX math formulas, beautiful tables,
  and syntax-highlighted code — directly in your terminal.</em>
</p>

<p align="center">
  <a href="#installation">Install</a> ·
  <a href="#usage">Usage</a> ·
  <a href="#features">Features</a> ·
  <a href="#comparison">vs glow / mdcat / bat</a> ·
  <a href="#faq">FAQ</a> ·
  <a href="#license">License</a>
</p>

<p align="center">
  <a href="https://github.com/Innomatica-GmbH/innomd/actions/workflows/tests.yml"><img alt="Tests" src="https://github.com/Innomatica-GmbH/innomd/actions/workflows/tests.yml/badge.svg"></a>
  <a href="https://pypi.org/project/innomd/"><img alt="PyPI" src="https://img.shields.io/pypi/v/innomd.svg?color=2567af"></a>
  <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue.svg">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg">
  <a href="https://innomatica.de"><img alt="by Innomatica" src="https://img.shields.io/badge/by-Innomatica%20GmbH-2567af"></a>
</p>

---

**innomd** is a command-line Markdown viewer for Linux and macOS that
renders LaTeX math (`$$…$$`, `$…$`, `\[…\]`, `\(…\)`) as clean Unicode,
so scientific notes, physics formulas, and technical documentation read
naturally in any terminal. Most CLI Markdown viewers — glow, mdcat, bat —
print `$$\lambda = \frac{b}{T}$$` as raw LaTeX source. `innomd` shows it
as a proper formula:

```
$$\lambda_{\text{peak}} = \frac{b}{T} \quad \text{with } b = 2{,}898 \times 10^{-3} \text{ m·K}$$
```

renders as

```
▌ λₚₑₐₖ = b/T   with b = 2,898 × 10⁻³ m·K
```

---

## Who is this for?

- Scientists, engineers, and students who keep notes in Markdown with
  embedded LaTeX math and want to read them in a terminal instead of a
  browser.
- Data scientists and ML engineers who want to skim `.ipynb` notebooks
  without starting Jupyter.
- Developers writing technical documentation (physics, ML, signal
  processing) who already use tools like `glow`, `mdcat`, or `bat` and
  miss proper math rendering.
- Anyone who prefers a fast, keyboard-driven Markdown preview over
  spinning up VS Code or a PDF viewer.

## Features

- **LaTeX math to Unicode**: `$$…$$`, `$…$`, `\[…\]`, `\(…\)`
  - Greek letters (`\lambda`, `\varepsilon`, `\sigma`, `\pi`, …)
  - Operators (`\cdot`, `\times`, `\nabla`, `\int`, `\sum`, `\propto`, `\approx`, …)
  - Fractions (`\frac`, `\dfrac`, `\tfrac`), roots (`\sqrt`, `\sqrt[n]{x}`)
  - Sub- and superscripts, including nested braces
  - `\text{…}`, `\vec`, `\hat`, `\bar`, `\dot`
  - Blackboard bold (`\mathbb{R}`, `\mathbb{N}`, `\mathbb{Z}`, …)
- **Jupyter notebook support** — pass any `.ipynb` file and it's rendered as
  Markdown: cells, code with syntax highlighting, stream and execution
  outputs.
- **Live reload** — `innomd --watch file.md` opens an interactive viewer
  that re-renders on every save and lets you scroll, search, and jump
  between matches — ideal for writing notes in one pane and previewing
  in another.
- **Theme presets** — 9 built-in color themes: `default`, `nord`, `dracula`,
  `gruvbox`, `solarized-dark`, `solarized-light`, `tokyonight`, `github`,
  `mono`. List with `innomd --list-themes`.
- **Rich Markdown rendering** via [rich](https://github.com/Textualize/rich):
  headings, lists, blockquotes, links, syntax-highlighted code blocks.
- **Beautiful tables** with rounded Unicode borders and column alignment.
- **Subtle horizontal rules** (`---` renders as centered `· · ·`).
- **Pager integration** (`less -R`) with automatic TTY detection.
- **Code-block safe** — math inside fenced code blocks is never substituted.
- **Pure Python** — one script, one dependency (`rich`), no Node, no Go toolchain.

## Installation

Requires Python 3.9+. The recommended way is [pipx](https://pipx.pypa.io/),
which installs `innomd` into its own virtual environment and exposes the
command on your `$PATH`:

```bash
pipx install innomd
```

On Ubuntu/Debian, if `pipx` is not yet available:

```bash
sudo apt install -y pipx && pipx ensurepath
```

Why not plain `pip`? Modern Linux distributions (Debian, Ubuntu,
Fedora, …) ship Python as PEP 668 *externally managed* and will reject
`sudo pip install`. Either use `pipx` (recommended) or install into a
virtual environment:

```bash
python3 -m venv ~/.venvs/innomd
~/.venvs/innomd/bin/pip install innomd
ln -s ~/.venvs/innomd/bin/innomd ~/.local/bin/innomd
```

To install from source (e.g. a specific commit or for development):

```bash
git clone https://github.com/Innomatica-GmbH/innomd.git
cd innomd
pipx install .           # or: pip install -e .   (editable, inside a venv)
```

### Windows (via WSL)

`innomd` depends on POSIX terminal APIs (`termios`, `tty`) for its
interactive watch mode, so it is developed and tested for Linux and
macOS. On Windows, use it inside the **Windows Subsystem for Linux**:

```powershell
wsl --install -d Ubuntu
```

Then inside your Ubuntu shell:

```bash
sudo apt install -y pipx && pipx ensurepath
pipx install innomd
```

Open a WSL tab in Windows Terminal — everything including watch mode,
mouse scrolling, and search works as on Linux.

## Usage

```bash
innomd README.md                  # render a file (uses pager on TTY)
innomd analysis.ipynb             # render a Jupyter notebook
innomd --watch notes.md           # live-reload preview
innomd -t dracula file.md         # use a preset theme
innomd -t nord -c dracula file.md # preset + override code theme
innomd --list-themes              # list available presets
cat notes.md | innomd             # pipe from stdin
innomd -P file.md                 # no pager
innomd -w 100 file.md             # fixed width
innomd -r file.md                 # raw preprocessed markdown
```

### Options

| Flag                    | Description                                   |
|-------------------------|-----------------------------------------------|
| `-P`, `--no-pager`      | Print directly, no pager                      |
| `-r`, `--raw`           | Output preprocessed markdown, no render       |
| `-w N`, `--width N`     | Force terminal width in columns               |
| `-t`, `--theme`         | Preset theme (see `--list-themes`)            |
| `-c`, `--code-theme`    | Override Pygments code theme only             |
| `-W`, `--watch`         | Live-reload: re-render on file change         |
| `--list-themes`         | List available preset themes                  |

### Watch mode

`innomd --watch file.md` opens a scrollable viewer that reloads on file
changes while keeping your scroll position. It's a small `less`-like
pager, no external dependencies.

| Key | Action |
|-----|--------|
| `j`, `↓` | line down |
| `k`, `↑` | line up |
| `space`, `PgDn` | page down |
| `b`, `PgUp` | page up |
| `g`, `Home` | jump to top |
| `G`, `End` | jump to bottom |
| `/pattern` + `Enter` | case-insensitive regex search |
| `n` / `N` | next / previous match |
| `:q` + `Enter` *or* `q` | quit |
| `:reload` *or* `:r` | force re-render |
| `Esc` | cancel `/` or `:` prompt |
| mouse wheel | scroll (3 lines per tick) |

Mouse scrolling uses SGR reporting (xterm 1006). Inside tmux, add
`set -g mouse on` to your `~/.tmux.conf`. When mouse reporting is
active, hold `Shift` to select text with the mouse — standard
xterm behaviour shared with `less`, `htop`, `vim`.

## Comparison

How `innomd` stacks up against other terminal Markdown viewers:

| Tool       | LaTeX math | Jupyter `.ipynb` | Live reload | Tables | Code highlighting | Images | Language |
|------------|:----------:|:----------------:|:-----------:|:------:|:-----------------:|:------:|:--------:|
| **innomd** | ✅ (Unicode) | ✅ | ✅ | ✅ | ✅ | — | Python |
| glow       | ❌ | ❌ | ❌ | ✅ | ✅ | — | Go |
| mdcat      | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ (Kitty/iTerm2) | Rust |
| bat        | ❌ | ❌ | ❌ | ❌ | ✅ (syntax only) | — | Rust |
| frogmouth  | ❌ | ❌ | ❌ | ✅ | ✅ | — | Python |

If you don't write formulas, use `glow` or `mdcat` — they're excellent.
If you do, this tool exists because nothing else did the job in the terminal.

## FAQ

**Does `innomd` render math like a LaTeX compiler?**
No. It substitutes LaTeX commands with Unicode glyphs. Matrices, large
alignments, and exotic notation will not look like PDF output. Physics
formulas, basic algebra, and common engineering notation render cleanly.

**Why Python and not Rust/Go?**
Because `rich` already solves 90 % of the Markdown-in-terminal problem,
and math preprocessing is a small layer on top. One dependency, one file,
no cross-compilation headaches.

**Why not just use a browser or VS Code preview?**
For quick notes, cat-ing a `.md` in the terminal is faster than opening
a GUI. This tool is for people who already live in tmux.

**Does it work on Windows?**
Not natively — `innomd` uses POSIX terminal APIs (`termios`/`tty`) for
its interactive watch mode. Use it via **WSL** (see the install
section). Inside WSL everything works identically to Linux.

## Limitations

`innomd` approximates LaTeX with Unicode — it will not render arbitrary math
to pixel perfection. Terminals can't. For papers, export to PDF with `pandoc`.
Notation that survives well: physics formulas, basic algebra, common operators.
Notation that degrades: matrices, commutative diagrams, large alignments.

## Development

Run the test suite (53 unit + end-to-end tests):

```bash
python3 -m unittest discover -s tests -t tests -v
```

CI runs the suite on Python 3.9 – 3.12 against every push and pull request.

## Contributing

Issues and pull requests welcome. Keep changes small and focused; there are
no runtime dependencies besides `rich`.

## License

[MIT](LICENSE) © 2026 Innomatica GmbH

Maintainer: Ivan Maradzhiyski &lt;ivan.maradzhiyski@innomatica.de&gt;

---

<p align="center">
  Built by <a href="https://innomatica.de">Innomatica GmbH</a> —
  software engineering for DACH and beyond.
</p>
