Troubleshooting Common Problems
- Frequent Source of Problems
- Markdown Documents Have Light Background Patches
- IDE Crashes or Hangs After New Version of the Plugin Is Installed
- JavaFX WebView HTML Preview Not Working
- GitHub Links Do Not Work
- Links do not work and Images do not show on GitHub
- Caret/Scroll Synchronization between text and preview does not work
- tags content is rendered below the tag
- Code and Fenced Code in Preview use proportional fonts
- Wrap on Typing not working
- License Installation and Activation
The plugin is actively developed to fix issues, add features and to update for the evolving
JetBrains API. If you are encountering errors or exceptions it is a good idea to make sure you
have the latest plugin version. Doing IDE Check for Updates... will check for a new release
version of the plugin.
Bug fixes and new features are released to the Early Access Program chanel of the plugin.
Frequently an issue will be fixed and released to the EAP channel weeks before the plugin is
released.
To enable EAP update channel:
- Select "Early Access Program" in
Check updates for: - Then make the IDE check for updates by selecting
IDE Check for Updates...from the menu.
This is caused by an incorrect parent scheme setting in the 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 all custom language plugins, including bundled with
the IDE, not just Markdown Navigator.
Example of a custom dark scheme with parent_scheme="Default" on the left and
parent_scheme="Darcula" on the right:
This used to be caused by caches being corrupt and is not affecting the IDE until 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 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.
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.
There are a few reasons images may show in preview but not on GitHub:
-
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.
-
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.
-
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 mvcommand 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 mvcommand 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 Commitcheck for painless detection and correction of git/file system case mismatches.
Caret and scrolling synchronization only works in the JavaFX WebView preview browser.
The plugin does not synchronize the top of the text window with the top of the preview window because this type of synchronization is not very effective for actual caret position in the text. Markdown elements and their rendered HTML elements can have very different visual size.
Caret position is synchronized in preview and optionally, horizontally aligned with the text caret, based on the markdown element at caret position.
The options for synchronization are found under the preview options:
The issue is caused by the way the plugin implements source position by wrapping the elements in
<div> tags. To get around that you either need to turn off scroll sync and show source
selection or add before to make the <details> tag interpret as inline HTML, which has
the benefit of allowing markdown rendering in the <summary> section.
The following works, including on GitHub.
<details id="todo"><summary>**To Do List**</summary>
#### Next Release To Do
* [ ] Add: status bar with information about selection: lines, code, comment and blank line
count.
* [ ] Add: reserved word list exclusion for preserve on paste. If pasting over reserved word
then don't make any changes to the pasted content.
* [ ] Add: Readme and Wiki Write up of Paste from History enhancements.
* [ ] Add: option and functionality to change duplicate lines action to only operate on a line
once even if there are many carets present on that line.
</details>
To Do List
- Add: status bar with information about selection: lines, code, comment and blank line count.
- Add: reserved word list exclusion for preserve on paste. If pasting over reserved word then don't make any changes to the pasted content.
- Add: Readme and Wiki Write up of Paste from History enhancements.
- Add: option and functionality to change duplicate lines action to only operate on a line once even if there are many carets present on that line.
The CSS for JavaFX WebView preview uses the following for fixed pitch font declarations. You can change this by adding your custom CSS Text to Languages & Frameworks > Markdown > Stylesheet in settings (preferences on OS X).
For JavaFX WebView preview browser:
var,
code,
kbd,
pre {
font: 0.9em Consolas, "Liberation Mono", Menlo, Courier, monospace;
}
For Swing preview browser:
code,
span.code,
samp,
var,
span.var,
kbd,
span.kbd,
span.tt {
font-family: Consolas, Inconsolata, "Liberation Mono", Menlo, Courier, Monospaced, monospace;
font-size: 1em;
}
Wrap on typing has a few settings that affect it:
Wrap on typing and soft wrapping can be mutually exclusive. The settings that control this are in Editor > Code Style > Markdown:
Wrap on typing drop-down selects the action to take for wrap on typing:
Selecting default will use the IDE wrap on typing setting. The others allow to control Markdown settings separate from the global IDE setting.
The Disabled if soft wrap is enabled will disable wrap on typing if soft wraps is enabled.
When disabled the toolbar button will reflect this disabled state and the pop-up on the toolbar
button will list the conditions causing it to be disabled.
Automatic actions such as insertion/deletion of list items or table rows and columns is also in Languages & Frameworks > Markdown > Editor in the Smart Keys Enter and Backspace sections:
Full description for these settings can be found in the Document Format Settings
To install the license you can paste the license code into the license box or load it from the
license server by clicking the Load License from vladsch.com and entering the e-mail and name
for the license in the dialog. Leave the password blank since no password is assigned to the
license until you assign one after logging in to vladsch.com, in
licenses under account settings:
The plugin uses the IDE proxy settings to communicate with the license server. Depending on how the proxy itself handles specific URL requests will affect the plugin communications.
If you are getting There was an error communicating with the license server consistently then
there is an error trying to reach the license server from your network.
On some corporate networks the secure connection through a proxy causes the communications to
fail. You can try turning off Use secure connection for license activation to see if it will
work:
