Adding GitHub Wiki to IntelliJ Project

GitHub wiki pages can be added as a sub-module of the main project and you will then be able to maintain the wiki in the IDE and use the Markdown Navigator plugin for editing and previewing the wiki pages.

The IntelliJ IDE's commit and push will update your GitHub Wiki Pages as a regular VCS root.

It makes it easy to add images into your wiki repository which is not as comfortable as adding images to GitHub issues where you can just drag and drop them from your computer.

Instructions

1. If you do not already have a GitHub wiki for your project (this you do on GitHub):

   1. Enable wiki's in the project settings by clicking the settings tab
   2. Create the wiki by clicking on the wiki tab in your repository.
   3. Save the page.

2. Clone the wiki to a subdirectory of your project. The wiki URL is your project URL's with .wiki.git at the end. For example idea-markdown URL is https://github.com/vsch/idea-multimarkdown its wiki git repository is at https://github.com/vsch/idea-multimarkdown.wiki.git. Clone it to the idea-multimarkdown.wiki subdirectory of the main project so that you can maintain these pages in the IDE using the plugin, while working on the plugin's source and so that the plugin will know that it is a wiki for the main project.

   ⚠️ Name the subdirectory with the same name as the main project directory and a .wiki suffix. Markdown Navigator uses this to treat all Markdown files below this directory as GitHub wiki pages for the project instead of regular Markdown files.

3. You will now see the the wiki sub-module in your project.

4. Add the wiki as a VCS sub-module to your IntelliJ IDE by going to Preferences on OS X and File/Settings on Windows and Linux, Version Control. IntelliJ is aptly named and it already detected an Unregistered VCS Root of the wiki subdirectory. Just click on the item for your wiki and then the + button at the bottom of the pane as in the image below:

   

5. GitHub Wiki Links check box is selected by default to match wiki link syntax of GitHub Wiki.

Maintaining wiki in the IDE

You can now rename files, drop images from your desktop and add these images to your wiki. When you commit your changes your GitHub wiki will be updated. Any changes made on the GitHub site will need to be pulled into the wiki on your repository.

In the plugin HTML Preview tab clicking on a Wiki Link for a file in your project will open the corresponding wiki page on GitHub, unless the file is marked ignored or newly added, in which case the file will be opened in the IDE so you can edit it or view it on the preview tab.

Links that are missing or incorrect, [[Missing Page Link]] will show up in the HTML Preview tab in red. Like this: Missing Page Link. They will also highlight as Unknown Symbol in the markdown text file. For example: .

The basic version does all the link validation for wiki links only. The enhanced will do it for all links based on GitHub rules for resolving relative links and optionally for all remote links.

In the enhanced version you can exchange a wiki link to explicit and back, you can also change explicit links between relative and absolute addressing. The plugin ensures that the links resolve and if they do not then a tooltip annotation is added and a quick fix intention action is offered that will fix the problem.

GitHub wiki link caveats

GitHub Wiki links with optional link text are the reverse of Creole's [[Link text|Link address]]. You can also append an anchor reference to the end of the link address via the #. If you get the order wrong and the link text resolves to a page then a quick fix will be offered to swap the text and address parts.

GitHub wiki link addresses cannot contain /, more accurately / will be changed to - in the rendered HTML href attribute. This means that you cannot put sub-directory references into the wiki links. On GitHub all wiki links resolve strictly by page name, even if these pages are located in sub-directories. This means that all your wiki pages must have unique names in order to be resolvable. Pages with duplicate names will resolve, as far as I have tested, to the first page, alphabetically sorted by path. Note that this means that a page with .markdown extension will match before one with a .md extension, if the file paths are the same.

This behaviour is duplicated by the plugin for GitHub wiki pages with any link that resolves to multiple pages annotated with a warning and all the pages are accessible via the line navigation marker, with the page that will be resolved to by the link at the top of the list and the rest below.

When you have duplicate matching pages you will get a warning annotation with some quick fixes to rename conflicting duplicate targets so that they can be targets of other links.

GitHub recommends using relative links in all pages as much as possible so that a repository, once forked will not have to be edited to correct for absolute links. Wiki pages are no exception but without the plugin resolving relative links is a pain.

Wiki pages resolves relative links differently than the rest of markdown documents. Relative image links have different rules than absolute links. Files with a non-markdown extension can be obscured by a markdown file with an embedded extension. For example, if you have a test.java file in the wiki and a test.java.md file, then you will not be able to create a link that resolves to the test.java file. The link will always resolve to test.java.md.

Another example is relative image links from wiki pages to the main repository. These must always reference the raw/... not the blob/... address prefix or they will not display on GitHub wiki page.

Keep this in mind when copying text between files. Link format change on copy/paste is not bullet proof and may result in broken links. Refactoring links within a file on file move is implemented in the Enhanced edition.

The easiest way to get the links right is to use completion in wiki links or in explicit link's address. If you want to resolve absolute addresses invoke the completions function multiple times, every invocation cycles to the next available link addressing format, or type https:// into the link and then start auto complete.

By default completions show markdown documents only. If you want to resolve to a non-markdown file extension just enter the extension in the address part of the link and launch auto-complete. You can combine the format and extension so [ ](https://.java) will show all available .java files using absolute https:// link format.

Adding Images

The easiest way to add images is to copy them into the wiki sub-module right in the IDE.

The enhanced edition allows image file drag'n'drop or direct pasting of images into the document. When pasting an image or dropping an image file located outside project, you will get an image options dialog which will let you select directory for the image, file name and link format options. It also allow minor tweaks like cropping, scaling, setting a transparent color, rounding corners, adding a border and adding highlights as options. It is the quickest way to create documentation images from screen shots.

You can organize your images by creating an img sub-directory, for example, under your wiki folder in the IDE and moving all your images into it. Refer to these images from the wiki pages via the img markdown syntax ![alt text](img/image-file-name.png). Having the images in a separate directory will clean up the main wiki folder.

To refer to the image files in your wiki folder use the img markdown syntax. For example, for an image file named image-file-name.png located in img directory the link would be ![alt text](img/image-file-name.png).

Moving images and updating references

Automatic changes to references for the moved images is only available in the enhanced version of the plugin, you can get a 15-day free trial here: Markdown Navigator Enhanced

As an alternative to the enhanced edition refactoring, if you want to move existing images from the root wiki folder then use the IDE's change in files feature and use Regular expression to rename all your image references.

File Naming Conventions

Page, Link address and text

The page title is the file name with dashes -, along with a few other characters, changed to spaces and the .md extension removed. It is automatically added by GitHub so you should not have an H1 header on the page.

You create links that refer to other pages by using the Wiki Link format: [[Page Name]]. GitHub converts this to a link to the HTML page of the markdown wiki page, with spaces changed to -. The plugin will automatically convert it to a markdown file reference, also with spaced changed to -.

To reference anchor links in pages just add the # after the page name [[Page Name#anchor-name]] if you want the link text to be different from the page link add it after | in the wiki link, [[Page Link Text|Page Name]] or if it has an anchor [[Page Link Text|Page Name#anchor-name]]

Anchor refs are created automatically matching GitHub rules so that they will resolve correctly when the links with anchor refs are navigated on GitHub.

You cannot have a wiki link with only an anchor reference as you can with explicit links. The plugin will highlight it as an unresolved link and offer a quick fix.

Custom Footer

If you want a custom footer for your wiki pages then create _Footer.md file in the root folder of your wiki and GitHub will use it as the custom footer for every page.

Custom Sidebar

If you want a custom sidebar for your wiki pages then create _Sidebar.md file in the root folder of your wiki and GitHub will use it as the custom sidebar for every page.