HTML Preview plugin¶

A full-fidelity, live preview of the active HTML (and PHP) document, rendered with a real browser engine (QtWebEngine) in a dockable panel. Unlike the Markdown preview, this renders CSS, JavaScript, web fonts and everything else exactly as a browser would.

Availability — not every download includes it

The HTML preview is driven by QtWebEngine, a complete browser engine, and is correspondingly large. It is therefore optional, and which download you have decides whether you get it.

macOS — OctoEdit is published as two packages: one with the HTML preview and a lean one without it. Choose the download that says it includes the HTML preview, and the preview is there the moment you start the editor. There is no add-on to install afterwards: a package without the preview cannot gain it later, so download the other one instead.
Windows — the preview can also be added to an existing installation later, as a separate HTML preview download that you unpack into the folder OctoEdit is installed in, then restart the editor.

If View ▸ HTML Preview is missing from the menu, your copy does not include the preview. The Markdown preview needs no browser engine and is always available.

Building from source: the preview sits behind the MTE_ENABLE_HTML_PREVIEW CMake option — see BUILDING.md for packaging and licensing notes.

Where to find it¶

View ▸ HTML Preview opens (or closes) the preview dock for the current tab.

How it behaves¶

Live render. The preview re-renders as you type (debounced; the debounce relaxes for very large files).
Full fidelity. Stylesheets, scripts, images and other resources load relative to the document's folder, so a page previews as it would in a browser.
Links to folders. Clicking a link that points at a local folder loads that folder's index document (index.html / index.htm / index.xhtml) instead of a directory listing.
Open in browser. The toolbar opens the on-disk file (or, for the PHP server modes below, the live URL) in your default browser.
Panel size. The preview keeps a share of the window rather than a fixed width, so it grows and shrinks with the window — see saved layout.

One flash with CPU window rendering

The preview brings a browser engine into the editor's window, and with Window rendering set to CPU the window has to be re-created to make room for it. The editor window therefore flashes once — the first time you open the HTML preview in a session, and never again after that. The default, GPU, avoids it entirely; see Preferences ▸ General ▸ Window rendering.

Preview visibility¶

Preview visibility is remembered per file, both during a session and across restarts:

Web files (.html, .htm, .xhtml, and .php / .phtml / .php3 / .php4) open the preview automatically the first time you view them.
Other files don't — but you can open the preview on any file with View ▸ HTML Preview, and it will render that file as HTML.
Within a session, your choice for a tab is restored when you switch back to it.
Across restarts, your explicit choice for a file is remembered: a manual close stays closed the next time you open that file, and a preview you opened on a file that wouldn't auto-open reopens. Files you never explicitly touched follow the auto-open default each time.

Previewing PHP¶

PHP runs on the server, so QtWebEngine cannot execute it directly. Choose how .php files are handled under Preferences ▸ Plugins ▸ HTML Preview:

Mode	What it does	Best for
Disabled	Shows an instructions page; never executes or fetches anything.	Turning PHP preview off.
Run with PHP (command-line)	Pipes the document through the local `php` binary and renders its output. Runs under PHP's CLI SAPI.	Templating / standalone files that echo HTML.
Run with PHP (built-in server)	Serves the document through PHP's built-in web server (`php -S`) that the editor starts and stops for you. Runs under the web SAPI.	Full pages — `phpinfo()`, `$_SERVER`, sessions, routing.
Use a server you run (URL)	Maps the open file to a URL on a server you run (Apache, nginx, Docker, `php artisan serve`, …).	An existing local dev stack.

The PHP executable path and Update automatically while typing apply to both command-line and built-in server modes. Leave the path empty to search your PATH and common install locations (on macOS, a Finder-launched app does not inherit your shell PATH, so set the full path, e.g. /opt/homebrew/bin/php).

Command-line vs. built-in server¶

These two modes both run the local php binary, but under different environments (SAPIs), and that changes what works:

Command-line (CLI SAPI). Fast and simple — it just shows whatever the script prints. But phpinfo() renders as plain text, and web features like $_SERVER, sessions and routing are limited or empty. Great for files that mostly emit HTML.
Built-in server (web SAPI). The editor launches a small php -S 127.0.0.1:<port> rooted at your file's folder and loads the page over HTTP, so it renders exactly like a real server: phpinfo() is a styled HTML page, $_SERVER is populated, sessions and asset/sub-resource requests all work.
The server is started only when you first preview a .php file in this mode, reused across renders, restarted if you switch to a file in another folder, and stopped when you close the editor or leave the mode.
It binds to 127.0.0.1 only, so it is never reachable from the network.
Unsaved edits are previewed too: your live buffer is written to a temporary file in the document's folder (so __DIR__ and relative include/require resolve correctly) and that is what's served. The temp file is replaced on each render and removed when you exit or switch modes.

Tip

If a PHP page shows up as text instead of a rendered page, switch from command-line to built-in server — that's the CLI-vs-web-SAPI difference, not a bug.

Use a server you run (URL)¶

If you already run PHP behind a web server, point the preview at it:

Base URL — your server's root, e.g. http://127.0.0.1:8000.
Document root — the local folder served at that base URL. The open file is mapped to a URL beneath it. Leave it empty to serve the file by name from the base URL. If the file is outside the document root, the preview reports that so you can fix the mapping.

When PHP isn't found¶

In the command-line and built-in-server modes, if no php binary can be located the preview shows a short error explaining how to set the path or install PHP. The Disabled mode's instructions page also links to PHP downloads and shows how to start a server.