org-preview-html

This minor mode provides an easy preview of your org-exported HTML files using either the eww or xwidget WebKit browser. By default, when org-preview-html-mode is enabled a save will trigger a refresh of the preview. Refresh frequency can be configured using org-preview-html-refresh-configuration (see Usage).

Installation

MELPA

The preferred way of installing this package is using MELPA. M-x package-install org-preview-html.

Manual

Download and copy org-preview-html.el into a directory in your load-path then (require 'org-preview-html).

Usage

Open an Org file and execute M-x org-preview-html-mode. A preview window opens next to the Org file. If you want to manage this window separate (aka, make it a frame) use the function org-preview-html-pop-window-to-frame.

Commands

• org-preview-html-mode - enables minor mode and opens preview.
• org-preview-html-refresh - manually refresh preview (only needed in manual mode).
• org-preview-html-pop-window-to-frame - pops out the current window in to a frame.

Variables/Configuration

Refresh Configuration

• org-preview-html-refresh-configuration - configure how often the HTML preview will be refreshed
  • If ‌'manual, update manually by running org-preview-html-refresh.
  • If ‌'save, update on save (default).
  • If ‌'export, update on manual export (using org-html-export-to-html).
  • If ‌'timer, update preview on timer.
    • Configure with org-preview-html-timer-interval, default 2 seconds.
  • If ‌'instant, update ASAP
    • Still WIP, it is suggested to use timer mode with a short interval.

Viewer

• org-preview-html-viewer - which Emacs browser org-preview-html-mode will use (default eww)
  • If ‌'eww, use eww browser (default).
  • If ‌'xwidget, use xwidget browser.
    • Requires Emacs to be built with xwidget support

Demo

This demo is using the xwidget browser. The author suggests utilizing the xwidget browser, though eww is set as default for the comfort of past users.

Limitations

It should be noted that as of now org-preview-html-mode officially supports previewing only one buffer at a time. Any suggestions on how previewing multiple buffers would work are welcome. It would be fairly trivial to implement preview support without any nice automatic switching/saving features; however, I would rather implement a smooth, pleasant experience rather than a janky one.

Todos

• Improve instant mode
• Auto-jump to current position in preview

Credits

Org-preview-html was originally written by lujun9972 (Darksun) and was originally titled (long ago) org-eww. It was rewritten by its current maintainer, jakebox. A thank you is due to Darksun for his long-time support and commitment.