Live Preview

By Lex Li

This article shows how live preview works.

Shortcuts

The keyboard shortcuts are

Operation

Windows/Linux

macOS

Preview

ctrl+shift+r

cmd+shift+r

Preview to Side

ctrl+k ctrl+r

cmd+k cmd+r

Note

To learn all keyboard shortcuts of this extension, please refer to Keyboard Shortcuts.

Settings

To learn more about the settings, refer to Configuration.

Preview Mode Selection

By triggering a preview, this extension might show a list of options,

../_images/selection.png

Once an option is chosen, this extension is going to render the preview page accordingly.

A status bar item is also added,

../_images/reset.png

By clicking this item, the selected option is reset, and the option list is displayed once again.

Explanation on Preview Modes

To show live preview pages, a mode is required to generate HTML from source files. Currently two modes are supported,

  • Esbonio

  • DocUtils

Esbonio

Warning

Esbonio language server must be enabled for live preview to work properly since release 171.0.0.

If live preview does not work, verify if “esbonio:” is visible in the status bar. Read “IntelliSense” section for more details.

If you are working on a Sphinx project, then this mode is highly recommended.

Esbonio is built upon Sphinx, which implements a rich set of syntax on top of what DocUtils offers, and it compiles the whole project (based on settings in conf.py) to a complete website. Its features are,

  • The rendering speed can be slow sometimes.

  • The preview page contains themed elements, and matches the final result in web browsers.

  • All Sphinx syntax and even extensions work flawlessly.

Note

If a large project is being worked on, it takes Esbonio a long while to compile the project behind the scene. Monitor “esbonio:” in status bar, so that you only trigger live preview when it finishes compiling.

DocUtils

DocUtils implements the very basic reStructuredText syntax, and it can render simple HTML pages even in worst cases. Its features are,

  • The rendering speed is super fast.

  • The preview page lacks of themes.

  • Certain Sphinx syntax is not rendered correctly.

This mode is only used as fallback in most cases.