innomd 0.4.0

Terminal Markdown viewer with LaTeX math, Jupyter notebooks, live reload, and themes.

innomd — Terminal Markdown Viewer with LaTeX Math Support

Render Markdown files with real LaTeX math formulas, beautiful tables, and syntax-highlighted code — directly in your terminal.

Install · Usage · Features · vs glow / mdcat / bat · FAQ · License

---

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.
• Mermaid diagrams — ```mermaid blocks render as Unicode/ASCII diagrams directly in the terminal:
  • Flowcharts with 14 node shapes (rect, round, stadium, diamond, hexagon, circle, parallelograms, trapezoids, double circle, …)
  • Sequence diagrams with lifelines, sync/async arrows, self-loops and loop/alt/opt block markers
  • Class diagrams with class boxes (name + member compartments) and UML edges (inheritance △, composition ◆, aggregation ◇, association ▶)
  • Gantt charts with date axis, task bars by state (done/active/ future), and after X dependency resolution
• 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: 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 — rich plus grandalf (a small layout library); no Node, no Graphviz binary, no Go toolchain. pipx install innomd is the only step you need, including for diagram rendering.

Installation

Requires Python 3.9+. The recommended way is pipx, which installs innomd into its own virtual environment and exposes the command on your $PATH:

pipx install innomd

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

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:

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):

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:

wsl --install -d Ubuntu

Then inside your Ubuntu shell:

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

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
--no-diagrams	Disable mermaid diagram rendering
--diagrams-ascii	Render diagrams with ASCII glyphs only
--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.

Mermaid diagrams

Fenced ```mermaid blocks are rendered inline as terminal-friendly diagrams. innomd auto-detects the diagram type from the first content line and dispatches to the appropriate renderer.

Flowcharts (graph / flowchart)

flowchart TD
  A[Start] --> B{Choice}
  B -- yes --> C((End))
  B -->|no| D([alt])
  D --> C

Supported syntax:

• Headers: graph TD|LR|BT|RL, flowchart TD|LR|BT|RL, with optional YAML frontmatter (---\ntitle: …\n---)
• Node shapes:
  • A[rect] — sharp box
  • B(round) — rounded corners
  • C([stadium]) — pill with parens on sides
  • D{decision} — heavy-line box; for short labels (≤6 chars) a true rhombus with ╱╲ slopes
  • E{{hexagon}} — double-line border
  • F((circle)) — indented top/bottom with curved sides
  • G[/parallelogram/], H[\parallel-alt\] — true leaning shapes
  • I[/trapezoid\], J[\trap-inv/] — bottom-/top-wider trapezoids
  • K[(cylinder)], L[[subroutine]], M>asymmetric], N(((stop)))
  • All accept quoted labels: A["with spaces & punct"]
• Edges: --> (arrow), --- (no arrow), -.-> (dashed), ==> (thick)
• Edge labels: A -- text --> B and A -->|text| B

Sequence diagrams (sequenceDiagram)

Lifelines (vertical bars) per participant, horizontal arrows per message in time order. Sync (->>), async (-->>), self-messages (rendered as small loops on the lifeline). loop/alt/opt/par blocks render as gestrichelt label markers. Participant boxes are repeated at the bottom so identities stay visible on long diagrams.

Class diagrams (classDiagram)

Class boxes show the name and member compartments (fields and methods). UML edge decorations: △ inheritance (at parent), ◆ composition, ◇ aggregation, ▶ association, dashed line for dependency, double arrow for bidirectional. Disconnected components are shelf-packed horizontally instead of stacked vertically, so a diagram with many small class pairs reads compactly.

Gantt charts (gantt)

Date axis with year/month-day ticks, task bars styled by state: █ done, ▓ active, ░ future. Tasks support absolute dates and durations (Nd/Nw), plus after <id> dependencies that resolve to absolute start dates automatically. Sections are rendered as labeled groups.

Implementation notes

Layout for flowcharts and class diagrams uses grandalf, a pure-Python Sugiyama layered-graph library — no external Graphviz binary required. Sequence and gantt diagrams have their own dedicated renderers because they are not graphs (lifelines + time order; bars on a calendar axis).

Anything outside the supported subset (gitGraph, mindmap, journey, ER, state machines, styling directives, subgraphs, modern @{shape:…} syntax) gracefully falls back to showing the original block as code, so unsupported diagrams never crash your render.

Use --diagrams-ascii if your terminal lacks Unicode box-drawing support, or --no-diagrams to skip rendering entirely and show the mermaid source as a normal code block.

Comparison

How innomd stacks up against other terminal Markdown viewers:

Tool	LaTeX math	Jupyter .ipynb	Live reload	Mermaid	Tables	Code highlighting	Images	Language
innomd	✅ (Unicode)	✅	✅	✅ (flowchart, sequence, class, gantt)	✅	✅	—	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):

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 © 2026 Innomatica GmbH

Maintainer: Ivan Maradzhiyski <[e-mail]>

---

Built by Innomatica GmbH — software engineering for DACH and beyond.