pi-markdown-preview

Preview assistant responses and local Markdown, LaTeX, code, diff, and other text-based files from pi in the terminal, browser, or as PDF, with math rendering, syntax highlighting, Mermaid, and theme-aware styling.

Screenshots

Preview adapts to your pi theme. Examples with a custom theme and the built-in defaults:

Terminal preview (custom theme):

Terminal preview (default dark):

Terminal preview (default light):

Browser preview (default dark and light):

Features

• Terminal preview (default) — 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$, $$display$$, \(...\), and \[...\] math via MathML with selective MathJax fallback for pandoc-unsupported browser/terminal equations, or native LaTeX (PDF)
• Syntax highlighting — fenced code blocks in markdown and standalone code files are rendered with theme-aware syntax colouring via pandoc. Supports 50+ languages including TypeScript, Python, Rust, Go, C/C++, Julia, and more.
• Annotation marker highlighting — inline [an: ...] markers are highlighted in terminal/browser/PDF previews as note-only chips (..., without the [an: ] wrapper) outside code blocks; long notes wrap correctly in PDF instead of running off the page
• Theme-aware — matches your pi theme (dark/light inference, export page/card colours, Markdown colours, accent colours, syntax colours)
• Response picker — select any past assistant response to preview, not just the latest
• File preview — preview arbitrary Markdown files (including .md, .mdx, .rmd, .qmd), LaTeX .tex files, diff/patch files, or code files (.py, .ts, .js, .rs, etc.) from the filesystem. LaTeX files are rendered as documents with full math and sectioning; diff files are rendered with coloured add/remove lines; code files are rendered with syntax highlighting.
• Caching — rendered pages are cached for instant re-display; refresh (r) bypasses cache

Prerequisites

• Pandoc (brew install pandoc on macOS)
• For terminal preview (/preview default): a Chromium-based browser executable (Chrome, Brave, Edge, Chromium). puppeteer-core is included as an extension dependency; no separate Puppeteer install is needed.
• For terminal inline display: a terminal with image support (Ghostty, Kitty, iTerm2, WezTerm)
• For PDF export (optional): a LaTeX engine, e.g. TeX Live (brew install --cask mactex on macOS, apt install texlive on Linux)
• For Mermaid-in-PDF support (optional): Mermaid CLI (npm install -g @mermaid-js/mermaid-cli) and 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>	Preview a Markdown, LaTeX, diff, or code file
/preview --file <path/to/file>	Preview a file (explicit flag)
/preview --browser	Open preview in default browser
/preview --font-size 14	Preview with a custom terminal/browser font size in px (defaults: terminal 16, browser 15)
/preview-browser	Shortcut for browser preview
/preview-browser <path/to/file>	Open a file preview in browser
/preview --pdf	Export to PDF and open
/preview-pdf	Shortcut for --pdf
/preview --pdf <path/to/file>	Export a file to PDF
/preview-clear-cache	Clear rendered preview cache
/preview --pick --browser	Pick a response, open in browser

Local images are supported. File previews resolve relative image paths against the previewed file’s directory; assistant-response previews resolve them against pi’s current working directory. Absolute paths, file:, http(s):, and data: image URLs also work.

Additional accepted argument aliases:

• Pick: -p, pick
• File: -f
• Browser target: browser, --external, external, --browser-native, native
• PDF target: pdf
• Terminal target: terminal, --terminal (usually unnecessary because terminal is the default)
• Font size: --font-size <px>, --font-size=<px>, --font-size-px <px>, --fs <px> (10–24 px; terminal/browser previews; defaults: terminal 16, browser 15)
• 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 Chromium detection for terminal preview rendering:

export PUPPETEER_EXECUTABLE_PATH=/path/to/chromium

Terminal preview uses the known-good fixed screenshot path: 1200px Chromium viewport at device scale 2. Set PI_MARKDOWN_PREVIEW_DEVICE_SCALE_FACTOR only if you want to experiment with screenshot density manually (default: 2; range: 1–2.5):

export PI_MARKDOWN_PREVIEW_DEVICE_SCALE_FACTOR=2

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