JCEF Preview

JCEF preview allows the most advanced rich preview of AsciiDoc content.

This is available from IntelliJ 2020.2+ and plugin version 0.31.x.

Update to IntelliJ 2020.3+ for the best experience, as this fixes some limitations of earlier versions.

Why to use the JCEF preview

The JCEF preview provides better HTML preview and additional features like scroll-to-view and opening links in the browser. As the preview is based on an up-to-date Google Chrome rendering engine, it offers in-par rendering compared to modern browsers. This includes rendering of fonts and SVGs.

Security options

If the user changes the Safe mode in the plugin’s settings from UNSAFE to any other mode, the preview in JCEF and JavaFX mode will restrict all content to the local project and will prohibit loading of external content using a content security policy (CSP). Starting with plugin version 0.36.6, all untrusted projects will default to the SECURE mode. The IDE shows a “Safe mode, limited functionality” notification once the user opens an AsciiDoc file.

Activate the dev tools for the JCEF preview to debug issues where the preview doesn’t show content due to CSP.

Limitations of the JCEF preview

When using tool windows in the undocked mode prior to plugin version 0.35.1, the preview will overlap with the tool window. See issue #751 for details.

The JCEF preview doesn’t support the IntelliJ proxy configuration prior to 2021.1. Configuring a proxy for JCEF requires an IDE restart. Therefore, remote images in the preview might not show for users behind a proxy. See ‘Proxy issues with the JCEF preview’ for more information.

Once a JCEF preview is open in a project, it now and then brings the focus to the project when editing files in a different window in IntelliJ 2020.2. This is fixed in the 2020.2.4 and 2020.3 release. See JetBrains issue “JCEF: steals focus from a different frame” for more information.

On macOS there is no copy-and-paste from the JCEF preview in IntelliJ 2020.2. This is fixed in IntelliJ 2020.3 (see issues IDEA-241604 and asciidoctor-intellij-plugin/#322). As a workaround, open the preview in the browser by clicking on your favorite browser symbol when hovering in the upper right corner of the editor and copying the contents of the browser window.

Benefits of the JCEF preview

JCEF preview is an embedded Chrome browser. After enabling the DevTools, users can right-click on the preview and use “Open DevTools”. This opens a fully equipped Chrome developer tools window that allows users to inspect the HTML created in the preview and to view the JavaScript console of the preview.

For IntelliJ 2021.3 and later

Set the registry key ide.browser.jcef.contextMenu.devTools.enabled to true to enable this feature.

The registry is available via menu Help  Find action…​, then enter “Registry” to search the action, then choose “Registry…​”. In the dialog that opens, start typing the registry key given above to restrict the list. Check the checkbox on the right to enable this property. Press Close to close the dialog. The DevTools are available for all newly opened editors. For editors already open, close and re-open them to see the DevTools. No IDE restart is required.

In IntelliJ 2021.3.1, closing the DevTools will also close the IDE. This is tracked in upstream issue IDEA-286008.

Possible Workarounds:

  • Enable “Confirm before existing the IDE” in the IDE’s settings. Once the DevTools have been closed for an editor, the editor needs to be closed and re-opened before DevTools can be opened again.

  • Disable registry option “ide.browser.jcef.asciidocView.osr.enabled”.

    With OSR disabled, the IDE doesn’t close any more on closing the DevTools; instead the preview goes blank once dev tools are closed (see IDEA-284130). Closing and re-opening the editor restores the preview.

    Once OSR is disabled, unpinned tool windows can no longer show above the preview (see IDEA-252845).

For IntelliJ 2021.2 and earlier

Enabling the internal mode for the IDE. This will enable DevTools after a restart. It will also enable additional internal menus of the IDE.

It will also enable additional diagnostic error messages like “Slow operations are prohibited on EDT” for all installed plugins.

When to use JCEF preview

JCEF preview is only available from IntelliJ 2020.2+ and plugin version 0.31.x. It requires that the user runs on the pre-packaged JetBrains OpenJDK 11.

Selecting a different JetBrains JDK using the “Choose Runtime” plugin

This is recommended for Android Studio 4.2 and 2020.3+ that doesn’t ship with either JavaFX or JCEF support. Watch this issue in Android Studio’s issue tracker for progress.

JavaFX preview that used to work with Android Studio 4.0 will not work with Android Studio 4.2 as it doesn’t package the necessary classes in the IDE. Therefore, follow these steps to enable JCEF preview for Android Studio.

For Android Studio 2021.1+:

  • Open menu item Help  Find action…​ and search for “Choose Boot Java runtime for the IDE…​”

  • Choose a runtime “11.0.x…​” labeled “JetBrains Runtime with JCEF” and install it. The IDE will restart.

  • Go to the settings of the AsciiDoc plugin and check if the preview is set to “JCEF Browser”. Change it to “JCEF Browser” if this is not the case.

For Android Studio 4.2 and 2020.3+:

  • Install the plugin “Choose Runtime”.

  • Open menu item Help  Find action…​ and search for “Choose Runtime…​”

  • Choose a runtime "jbrsdk-11_0_…​tar.gz" or later and install it. The IDE will restart.

  • Go to the settings of the AsciiDoc plugin and check if the preview is set to “JCEF Browser”. Change it to “JCEF Browser” if this is not the case.