Skip to content

Debug Settings

Vladimir Schneider edited this page Dec 23, 2018 · 4 revisions

Debug settings are used for internal debugging options, including JavaFX WebView debugging using Google Chrome Dev Tools.

ℹ️ Not all settings are available in the enhanced edition. Internal debug settings are only enabled for internal development or by request.

Settings are found in Languages & Frameworks > Markdown > Debug:

debug-settings

  • Reload open editors when the underlying file type changes: enables prompting to close and reopen editor when underlying file type or associated editor for the file changes.

  • Reinitialize editors on settings change: enables reinitializing editors when settings change which affect editor display. This occurs when some markdown gutter icons are disabled but the editor gutter width is not reduced until the editor is reloaded or is forced to reinitialize.

  • Change editor highlighter to Lexer based for all read-only editors: enables forcing syntax highlighter to Lexer for read-only files. Read-Only files do not have an annotation phase and do not show syntax highlighting when Annotator syntax highlighter is selected.

  • Show text formatting bounds: enables highlighting of bound highlighting for markdown element at caret

  • Show combination colors: enables display of programmatically created syntax highlighting colors in Editor > Color Scheme > Markdown. There are a lot of blended syntax colors created and not displayed. Enabling this option will show over a thousand color combination so do not enable unless you really need to see these synthesized colors names.

  • Throw parser exceptions: passes parser exceptions through to the IDE. Only needed for parser debugging.

  • Error highlight remote URL elements until content is fetched.: when remote URL validation is enable, enabling this option will treat the remote reference as invalid until its content is retrieved from the URL. Otherwise, error highlighting is only done when retrieved content results in error. ⚠️ Enabling this option will cause all remote links to flash error color until content is fetched.

  • Output remote URL fetch exceptions to console: when remote URL validation is enable, enabling this option will output exception stack trace to the console. Only visible if running IDE from command line or debugging plugin under IDE.

  • Enable JavaFX Preview Script Debugging: enables Google Chrome Dev Tools debugging for JavaFX WebView. See JavaFX WebView debugging with Google Chrome Dev Tools

  • Test File Directory: debugging option to allow collecting markdown documents into a single directory for testing.

  • Flexmark Spec Example: rendering option for flexmark-java spec test example. Only enabled by request for flexmark-java extension developers.

  • Preference Dialog Width, Preference Dialog Height: settings dialog height and width to set using the Size preferences dialog. This option is used in combination with Size preferences dialog action to change the size of the settings/preferences dialog. Used to make consistent screenshots of the settings dialog.

  • Translation: translation settings.

    • from locale of original document content
    • to locale of desired document content
    • Auto detect language, an attempt is made to auto detect document language. Translations work best if you select the correct source language.
    • Set Key opens

    ℹ️ Requires Yandex API key which is free of charge.

JavaFX WebView debugging with Google Chrome Dev Tools

Starting with version 2.5.0, enhanced plugin has JavaFx WebView Debugger for Google Chrome Dev Tools integrated into the preview window for comfortable JavaFX WebView debugging of scripts, HTML and CSS.

Disclaimer

⚠️ WebView debugging with Chrome Dev Tools is implemented using the undocumented WebView debugger interface which has been known to cause application crashes under some conditions. Its stability is highly dependent on the OS and JDK version used in your system. To try out the debugging of JavaFX WebView on your system, outside the IDE environment you can use the Web View Debug Sample jar file and get a preview of the debugging experience.

Note Default system JDK may differ from the one used by the IDE, which can be configured separately and can use a bundled JDK implementation.

⚠️ To eliminate the risk of loosing unsaved work, it is recommended that Preview debugging be first tried in a separate IDE instance to make sure it is stable on your system. When WebView crashes it tends to take the whole application with it. No warnings, no messages, no goodbyes.

Enabling Debugging

To enable debugging you need to enable debugging in Languages & Frameworks > Markdown > Debug:

debug-settings

  • Enable JavaFX Preview Script Debugging: enable to see the debug related buttons in the preview toolbar.

  • JavaFX Preview Resource URL: url to use for page and resources used by the preview. Without debugging, the page content is passed to WebView as a string. For debugging a URL is needed to allow access to scripts and stylesheets. Use file:// based URL and point it to a directory where a copy of the preview resources and generated HTML pages are located.

    If you have a web server on localhost then you can also use a public sub-directory for this purpose.

  • Use page serial query param: WebView caches remote resources and uses the cached version for all subsequent rendering. When the resource content changes these will not be reflected in the page. To make WebView reload the resource a query parameter is appended to its URL and incremented every time a file change is detected. This only works for files which are monitored by the IDE. Effectively they need to be in a directory marked as source, test or resource roots.

  • JavaFX Preview Resource Dir: directory in the file system corresponding to the resource URL directory above.

  • JavaFX Preview Debugger Port: configures which port to use for the web-socket server used with Chrome Dev Tools connection

Once debugging is enabled in settings, you can use the Debug On button: debug-on-button to start/stop web socket server for individual markdown documents. If you need to debug start up scripts in the document body, you can use the reload and pause button debug-reload-pause to pause execution on the first executable script in the body of the page.

Start server action will copy the Debug URL for Chrome Dev Tools to the clipboard. Open Google Chrome and paste this URL into the address bar. It also pops-up a notification balloon with an action to Launch Chrome Browser:

debug-on-balloon

Launching Chrome Browser will launch the default browser which is configured in the IDE and bring up the instruction page:

Debug URL was copied to the clipboard.

Paste it into the address bar and hit ENTER to debug

If you get "This site can't be reached" error

  • Delete the trailing /?# of the URL and Hit ENTER
  • You should see the debugging tools initialized.
  • Now paste the full URL into the address bar and hit ENTER

This is only required to be done once, until you quit Chrome.

Only the first debug session cannot use /?... query parameters after the ws parameter.

NOTE Occasionally, WebView debugger and Chrome Dev Tools do get out of sync and the only way to restore harmony is to re-open the markdown file to get a new WebView instance and re-establish a new connection to Dev Tools.

NOTE Sometimes the shutdown process of the web-socket server fails to release the port and attempts to start it again will result in Server address is in use error.

debug-start-failed

Use the links in the Notification balloon to increment/decrement the port and retry the operation rather than wait for the address to be released.

Translation Settings

This is an experimental feature allowing translation of the markdown document Powered by Yandex.Translate. As all automatic translations, the results should not be used as final copy. This feature is instead intended as a convenience when working with documentation in a foreign language.

To use document translation requires entering the Yandex API key which can be obtained free of charge.

Click the Set Key button to open the dialog, which also provides a link to the Yandex API page with instructions on getting the Yandex API key.

Screenshot Translation Set Key

Paste the key into the dialog. This key will be used for document translations.

Select the following options:

  • from locale of original document content
  • to locale of desired document content
  • Auto detect language, an attempt is made to auto detect document language. Translations work best if you select the correct source language.

This will enable the Translate Document Editor Actions Translate Document action in the drop down menu of the toolbar and under the Tools/Markdown Navigator/Export menu.