JCEF Preview
JCEF preview allows the most advanced rich preview of AsciiDoc content.
|
The JCEF preview is the only rich preview. The JavaFX preview is no longer available, as JetBrains removed JavaFX support for plugins from IntelliJ 2025.1. |
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.
How to enable the JCEF preview
The JCEF preview is the default when it is available. If the preview was changed, the user can change it back the preview to JCEF in the plugin’s settings via .
Security options
If the user changes the Safe mode in the plugin’s settings from UNSAFE to any other mode, the preview in JCEF mode will restrict all content to the local project and will prohibit loading of external content using a content security policy (CSP). 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
The following paragraphs describe problems where either a workaround is available or a fix is the latest version of IntelliJ or the AsciiDoc plugin.
Preview not showing on RDP (workaround available)
When using RDP to access the IDE, a user might not see the preview, and it appears as a blank space. This might be due to issue IDEA-299007. The root is that hardware acceleration is not available for the preview.
As a workaround, set the registry option ide.browser.jcef.gpu.disable to true.
The registry is available via menu , 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. Restart the IDE to apply the setting.
Benefits of the JCEF preview
JCEF preview is an embedded Chrome browser. 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.
|
In IntelliJ 2021.3.1+, closing the DevTools will also close the IDE. This is tracked in upstream issue IDEA-286008. This seems to be fixed in 2024.1.+. Possible Workarounds:
|
- Using an action
-
Use the menu item and choose “Open Devtools Window for the current AsciiDoc Preview”.
Users can define their own shortcut in the Keymap settings entry for this action.
- For IntelliJ 2022.3 and later
-
Set the registry key
ide.browser.jcef.contextMenu.devTools.enabledtotrueand setide.browser.jcef.asciidocView.osr.enabledto false to enable this feature.Once OSR is turned off, unpinned tool windows can no longer show above the preview (see IDEA-252845).
The registry is available via menu , 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. Right-click on the preview and use “Open DevTools”. For editors already open, close and re-open them to see the DevTools. No IDE restart is required.
- For IntelliJ 2021.3 and later
-
Set the registry key
ide.browser.jcef.contextMenu.devTools.enabledtotrueto enable this feature.The registry is available via menu , 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. Right-click on the preview and use “Open DevTools”. For editors already open, close and re-open them to see the DevTools. No IDE restart is required.
- 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 the JCEF preview is available
The JCEF preview requires that the user runs the IDE on the JetBrains Runtime that is pre-bundled with the IDE. Install the IDE with the JetBrains Toolbox to always get the matching runtime, and let the Toolbox keep the IDE up-to-date. Don’t use IDE packages from a Linux distribution, as they usually lack the JetBrains Runtime with JCEF.
Selecting a different JetBrains JDK using the “Choose Runtime” plugin
This is recommended for Android Studio that doesn’t ship with JCEF support. Watch this issue in Android Studio’s issue tracker for progress.
-
Open menu item and search for “Choose Boot Java runtime for the IDE…”
-
Choose the newest runtime 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.