Heze

Headless Markdown and SVG previewer with deterministic PNG export.

Features · Installation · Quick start · CLI · Ruby API · Development

Heze is a headless Markdown and SVG previewer with deterministic PNG export. It keeps the parsed document tree independent from the renderer, then uses Zaniah for native previews and image output.

Features

GitHub Flavored Markdown — headings, lists, quotes, tables, fenced code, links, and images.
Validated SVG input — unsupported filters, masks, text, and gradients fail before rendering.
Deterministic PNGs — export the same document at an explicit width and height.
Native preview — automatic macOS, Linux, and Windows backends with a textual fallback.
Live reload — watch a document while editing, or browse a directory of Markdown files.
Syntax highlighting — fenced code blocks are highlighted through Antares and Rouge.
Encoding detection — UTF-8 BOM and Japanese Windows-31J input are handled safely.

Installation

gem install heze

Heze requires Ruby 3.2 or newer.

Quick start

Open a native preview:

heze README.md

Export a deterministic PNG:

heze README.md --width 1200 --height 800 --export preview.png

Pass a directory to browse its Markdown files:

heze docs/

CLI

Usage: heze PATH [options]

Option	Description	Default
`--export PATH`	Write a PNG instead of opening a preview	—
`--width N`	Preview or export width	`900`
`--height N`	Preview or export height	`1000`
`--theme NAME`	Select a named theme	`dark`
`--backend NAME`	`auto`, `headless`, `tui`, `mac`, `linux`, or `windows`	`auto`
`--watch`	Watch for changes outside an interactive preview	off
`--no-watch`	Disable interactive live reload	off

Static SVG files use the same preview and export flow:

heze assets/mark.svg --export mark.png

Ruby API

Parse Markdown into an immutable document tree and render it directly:

require "heze"

document = Heze::Markdown.parse("# Hello\n\nRendered by Heze.")
png = Heze::Renderer.new(width: 1200, height: 630).render(document)
File.binwrite("preview.png", png)

Development

bundle install
bundle exec rake
bundle exec rbs -I sig validate
gem build --strict heze.gemspec

Contributing

Bug reports and pull requests are welcome on GitHub.

License

Heze is available under the MIT License.

heze

Runtime