pi-markdown-preview

Rendered markdown and LaTeX preview for pi. Preview assistant responses or arbitrary markdown files directly in your terminal, browser, or as PDF, with full math rendering, syntax highlighting, and theme-aware styling.

Screenshots

Preview adapts to your pi theme. Examples in dark and light:

Terminal preview (dark):

Terminal preview (light):

Browser preview:

Features

• Terminal preview — renders markdown as PNG images displayed inline (Kitty, iTerm2, Ghostty, WezTerm). Long responses are automatically split across navigable pages.
• Browser preview — opens rendered HTML in your default browser as a single continuous scrollable document
• PDF export — exports markdown to PDF via pandoc + LaTeX and opens it in your default PDF viewer
• Mermaid diagrams — renders ```mermaid code blocks as SVG diagrams in terminal/browser previews, and as high-quality vector diagrams in PDF export when Mermaid CLI is available
• LaTeX/math support — renders $inline$ and $$display$$ math via MathML (browser/terminal) or native LaTeX (PDF)
• Theme-aware — matches your pi theme (dark/light, accent colours)
• Response picker — select any past assistant response to preview, not just the latest
• File preview — preview arbitrary .md files from the filesystem
• Caching — rendered pages are cached for instant re-display; refresh (r) bypasses cache

Prerequisites

• A Chromium-based browser (Chrome, Brave, Edge, Chromium)
• Pandoc (brew install pandoc on macOS)
• A terminal with image support (Ghostty, Kitty, iTerm2, WezTerm) for inline preview
• A LaTeX engine for PDF export (optional): TeX Live (brew install --cask mactex on macOS, apt install texlive on Linux)
• Mermaid CLI for Mermaid-in-PDF support (optional): npm install -g @mermaid-js/mermaid-cli (requires a Chromium browser accessible to Mermaid CLI)

Install

pi install npm:pi-markdown-preview

Or from GitHub:

pi install https://github.com/omaclaren/pi-markdown-preview

Or try it without installing:

pi -e https://github.com/omaclaren/pi-markdown-preview

Usage

| Command | Description | |---------|-------------| | /preview | Preview the latest assistant response in terminal | | /preview --pick | Select from all assistant responses | | /preview <path/to/file.md> | Preview a markdown file | | /preview --file <path/to/file.md> | Preview a file (explicit flag) | | /preview --browser | Open preview in default browser | | /preview-browser | Shortcut for browser preview | | /preview-browser <path/to/file.md> | Open a file preview in browser | | /preview --pdf | Export to PDF and open | | /preview-pdf | Shortcut for --pdf | | /preview --pdf <path/to/file.md> | Export a file to PDF | | /preview-clear-cache | Clear rendered preview cache | | /preview --terminal | Force terminal preview output | | /preview --pick --browser | Pick a response, open in browser |

Additional accepted argument aliases:

• Pick: -p, pick
• File: -f
• Browser target: browser, --external, external, --browser-native, native
• PDF target: pdf
• Terminal target: terminal
• Help: --help, -h, help
• Note: --pick and --file cannot be used together

To validate command docs against implementation:

npm run check:readme-commands

Keyboard shortcuts (terminal preview)

| Key | Action | |-----|--------| | ← / → | Navigate pages | | r | Refresh (re-render with current theme) | | o | Open current preview in browser | | Esc | Close preview |

Configuration

Set PANDOC_PATH if pandoc is not on your PATH:

export PANDOC_PATH=/usr/local/bin/pandoc

Set PANDOC_PDF_ENGINE to override the LaTeX engine used for PDF export (default: xelatex):

export PANDOC_PDF_ENGINE=xelatex

Set PUPPETEER_EXECUTABLE_PATH to override browser detection:

export PUPPETEER_EXECUTABLE_PATH=/path/to/chromium

Set MERMAID_CLI_PATH if mmdc is not on your PATH:

export MERMAID_CLI_PATH=/path/to/mmdc

Set MERMAID_PDF_THEME for PDF Mermaid rendering (default, forest, dark, neutral; default: default):

export MERMAID_PDF_THEME=default

Cache

Rendered previews are cached at ~/.pi/cache/markdown-preview/. Clear with:

/preview-clear-cache

Or manually:

rm -rf ~/.pi/cache/markdown-preview/

License

MIT