# org-preview-html

**Repository Path**: uphiel/org-preview-html

## Basic Information

- **Project Name**: org-preview-html
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-10-24
- **Last Updated**: 2023-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#+TITLE: org-preview-html
#+AUTHOR: jakebox
#+OPTIONS: num:nil toc:nil ^:{} 

[[http://melpa.org/packages/org-preview-html-badge.svg]]

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][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.
[[org-preview-html-demo.gif]]

* 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 [[https://github.com/lujun9972][lujun9972 (Darksun)]] and was originally titled (long ago) org-eww. It was rewritten by its current maintainer, [[https://github.com/jakebox][jakebox]]. A thank you is due to Darksun for his long-time support and commitment.