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.

Optional component

The HTML preview links QtWebEngine, a heavy dependency. It is an opt-in build (MTE_ENABLE_HTML_PREVIEW, on by default) and is only present when Qt WebEngine is available. A build without it omits this plugin entirely and links no QtWebEngine. 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.

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.