Overview

The org preview shows the rendered document next to (or instead of) the source, the way VS Code's Markdown preview does for .md files. It uses the same engine as HTML export (Export), so what you see is what HTML export produces, and it updates as you type.

Opening the Preview

Action	macOS	Windows/Linux	Command
Open preview (in this group)	`Cmd+Shift+V`	`Ctrl+Shift+V`	`scimax.org.preview.open`
Open preview to the side	`Cmd+K V`	`Ctrl+C Shift+V`	`scimax.org.preview.openToSide`
Back to the source from preview	`Cmd+Shift+V`	`Ctrl+Shift+V`	`scimax.org.preview.showSource`

The preview icon in the editor title bar of an org file also opens the preview to the side, and the preview's own title bar has a button that goes back to the source. Each org file has at most one preview; running the command again reveals the existing one.

The older command scimax.org.previewHtml (Scimax: Preview HTML, also reachable from the export menu) now opens this live preview to the side.

What the Preview Does

Live updates: the preview re-renders shortly after you stop typing (see scimax.orgPreview.updateDelay) and when you save. The page is updated in place, so it does not flicker and keeps its scroll position.
Math: LaTeX fragments ( $x^2$ , \[...\], equation environments) are typeset with MathJax.
Code: source blocks are highlighted with highlight.js, in a light or dark style that follows the VS Code theme.
Images: local images such as [[./figure.png]], file: links and Jupyter results in .ob-jupyter/ are shown. Images outside the document folder and workspace are allowed as they are found.
Theme: colours, fonts and code backgrounds follow the VS Code theme.
Citations: cite: links are formatted against the files named by #+BIBLIOGRAPHY: / = as in HTML export. The bibliography is re-read only when the .bib file changes.
#+INCLUDE: directives are expanded.

Scroll Sync and Navigation

Scrolling the source editor scrolls the preview to the same place, and scrolling the preview scrolls the editor. Each direction can be turned off (see Settings).
Double-click in the preview to move the cursor to that place in the source. Collapsed headings, blocks and drawers around that line are unfolded so the text is visible.
Links: http(s) and mailto links open in the browser; # links jump within the preview; links to files (including other .org files) open in the editor.
Links within the document: [[#custom-id]] jumps to the heading with that CUSTOM_ID, and [[*Heading]] to the heading with that title. Without a description they show the heading's section number (its title when the file has #+OPTIONS: num:nil), as Emacs does, so Section [[#sec:results]] reads "Section 2".
Back: after following a link within the preview (a citation to the bibliography, a reference to a section, a footnote), a ← Back button appears at the top right, and Cmd+[, Cmd+Left (Ctrl+[, Ctrl+Left elsewhere) or Backspace return to where you were. Each jump is remembered, so you can go back several times. The target is briefly highlighted.

Sync works at the level of headlines, paragraphs, lists, tables and blocks. Inside a long element the position is interpolated. After an #+INCLUDE: directive, the included lines shift the line numbers, so sync can drift below the include point.

Settings

Setting	Default	Description
`scimax.orgPreview.updateDelay`	`300`	Milliseconds after typing before the preview updates
`scimax.orgPreview.scrollPreviewWithEditor`	`true`	Scroll the preview when the source editor scrolls
`scimax.orgPreview.scrollEditorWithPreview`	`true`	Scroll the source editor when the preview scrolls

Security

Source blocks are never executed by the preview. Scripts in the document (for example in #+HTML: blocks or #+HTML_HEAD:) do not run either: the preview's content security policy allows only its own scripts and the MathJax and highlight.js files on their CDNs. Because those libraries load from the network, math and highlighting need an internet connection; the rest of the preview works offline.