Troubleshooting Common Problems

Frequent Source of Problems

⚠️ Markdown plugins conflict with each other. If you have more than one markdown plugin installed then you need to make sure that only one is enabled at a time. The only exception to this is GFM which provides a preview rendered by chromium browser engine and markdown to HTML converted by GitHub. It does not provide any language based features that create the conflict between other markdown plugins.

Markdown Documents Have Light Background Patches

This is caused by an incorrect parent scheme setting in your custom scheme. The custom scheme file can be found in the color subdirectory of the JetBrains product you are using and the file will have the name of your scheme and a .icls extension.

For a dark scheme the first line should have Darcula as the parent_scheme attribute: <scheme name="YourSchemeName" version="142" parent_scheme="Darcula">.

If it is Default then you need to change parent_scheme="Default" to parent_scheme="Darcula". Otherwise, the IDE uses the wrong default colors from the plugin default color map. This would also affect other custom language plugins not just Markdown Navigator.

Here is an example of a custom dark scheme with parent_scheme="Default" on the left and parent_scheme="Darcula" on the right:

IDE Crashes or Hangs After New Version of the Plugin Is Installed

This is usually caused by caches being corrupt and is not noticed after installing a new custom language plugin that requires re-indexing. Invalidate caches and restart. If the problem persists please open an issue in GitHub: GitHub Issues

If you are using JavaFX WebView preview browser and your JRE is an Oracle JRE older than 1.8.0u51 then it is quite possible that the combination is not stable. You should change the JRE to at least 1.8.0u51, which has shown to be the first stable version for use of JavaFX WebView preview browser for this plugin. Earlier versions of WebView have trouble with some image formats so your crashes can be content dependent.

JetBrains bundled JRE older than 1.8.0u40b105 have also shown some issues with stability when displaying certain image files.

JavaFX WebView HTML Preview Not Working

Some users are not able to use the JetBrains bundled JRE in IDE versions 2018 with OS X High Sierra (10.13.x). A possible solution may be creating JDK from the Bundled JRE and using it as the boot JDK for the IDE.

JavaFx WebView preview requires JDK 1.8.0u40 or later that includes jfxrt.jar in the JDK's lib/ext directory, which is its standard location.

If jfxrt.jar is not found or the plugin cannot create the new editor class due to errors, it will fall back to using the Swing preview browser: JEditorPane with HTMLEditorKit preview.

If you change the boot JDK, see Changing Boot JDK for instructions, and want the plugin to use the JavaFX preview, select the JavaFX as the Preview browser in Preferences on OS X and File/Settings on Windows and Linux, Languages & Frameworks > Markdown.

GitHub Links Do Not Work

In order for the links in the preview tab to resolve to corresponding files on GitHub the file must be under a git vcs root, the directory where target files are located must be part of the project's files and not marked as excluded.

Multiple vcs roots are supported. A file is considered under the vcs root that is above it in the directory hierarchy. Files with status UNKNOWN, IGNORED and ADDED are considered not to have remote counterparts.

For all files that don't have remote counterparts the links will resolve to local files. This includes files that were added but not yet committed.

Relative links from GitHub markdown documents in main the repository to wiki pages should be prefixed with ../../wiki because the documents in the root of the main repository are located at /blob/branch and wiki pages are in /wiki. The same applies to issues, pulls, graphs, pulse. Relative links will resolve to the same pages as they would on GitHub using the same relative links.

If you are clicking on a link that you expect to have a remote but a local file opens then the file does not resolve to a remote as far as the plugin is concerned. It could be because the remote origin has no URL that is an http: or https: protocol or it lacks a .git extension. Also the file should have been committed at least once so that it looses its ADDED status.

Links do not work and Images do not show on GitHub

There are a few reasons images may show in preview but not on GitHub:

1. Image files were not committed to the repository. In this case the preview images will have a warning frame around them and links will show in warning (dark yellow/light brown) and links and image elements in text will have a warning annotation.

2. Image link is not pointing to the raw file content. Browsers cannot display images which point to the default file page on GitHub. Image links have to point to the raw file content address for the image file.

   In this case the markdown text editor will show a warning annotation that the image link is not correct. Use the appropriate intention to change link to raw content.

3. On case-insensitive file systems: Image file and link file name case are mismatched. This can happen if the original file was added to git and was subsequently renamed with only case changes without using the git mv command to rename the file in the git index.

   Since the file system is not case-sensitive the new file name will continue to update without issues and git will not be aware of the name change. However, when the repository is pushed to GitHub the file name stored in git and not the file system will be used.

   The plugin uses the file system name to resolve links. This will result in links and images referencing files which do not exist on GitHub since GitHub repositories are case sensitive.

   Resolving name case mismatch is simple with the use of git mv command to tell git that the file name has changed.

   I have been bitten by this problem several times and wasted enough time looking for a bug in the plugin, only to realize that it is an issue of file/git case mismatch. The last such time waster was enough to prompt me to create a plugin specifically to deal with this issue.

   Git File Case Fixer Plugin will check case-insensitive file systems for file mismatches in git and optionally correct the file case in git or the file system. This check can be done manually or as a Before Commit check for painless detection and correction of git/file system case mismatches.