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 MultiMarkdown plugin for editing and previewing.

The IntelliJ IDE's commit and push will update your GitHub Wiki Pages.

It also 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 don't 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. I cloned it to the idea-multimarkdown.wiki subdirectory of the main project so that I can maintain these pages in the IDE using the plugin, while working on the plugin's source.

   Name the subdirectory with a .wiki suffix. MultiMarkdown uses this marker to treat all Markdown files below as GitHub wiki pages and not 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 > 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. Currently GitHub syntax check box is selected and disabled in Preferences > Other Settings > MultiMarkdown > Markdown Extensions. GitHub's wiki links, with optional link text, have link text come before the link address in wiki links, which is reversed from Creole wiki link syntax. GitHub syntax is either [[Link Text and Address]] or [[Link Text|Link Address]].

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. In the enhanced version you can exchange a wiki link to explicit and back, you can also change exiplicit links between relative and absolute addressing. The plugin ensures that the links resolve and if they do not then a pop-up annotation is created with a quick fix intention action 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. All 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 .mardown extension will match before one that has 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. Trust me, I have spent weeks testing and trying to get it right and still cannot always figure out at a glance why a relative link will not resolve. The reason is simple: bugs!!!. The wiki home page resolves relative links differently than the rest of the pages. Also, 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 resolve. Absolute addresses are not affected, neither are explicit links.

From the home page relative image links resolve as if the Home.md file was located in the main repository, instead of under the wiki/ sub-directory. This means from the home page, relative image links must begin with wiki/. The same for explicit links, except in the case of explicit links they will resolve both ways, with or without the wiki/ prefix.

Keep this in mind when copying text between files. Refactoring on copy/paste is not yet implemented. Neither is link refactoring contained in a file if it is moved or renamed. This is a near future implementation.

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 just type https:// into the link and then start auto complete. Similarly, if you want to resolve to a non-markdown file extension just enter the extension in the address part of the link and launch autocomplete. You can combine the two so [ ](https://.java) will show all available .java files using absolute links.

Adding Images

I found the easiest way to add images is to take a screenshot, then drag-drop-copy (by holding down (Ctrl or ⌘ depending on your OS) into the wiki sub-module right in the IDE and rename the file in the Copy File dialog that pops-up.

Don't use the drag-drop-move from your desktop because the IDE will complain that the file is outside the project, which it is. Copy it instead, using drag-drop-copy if you want, and add it to source control.

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).

NOTE For the Home page you will need to include the either full GitHub URL to images in your wiki or add wiki/ prefix to all relative image link addresses. The Home page resolves image link addresses relative to the main repository URI not the wiki URI. For the example above the link in the wiki home page should be ![alt text](wiki/img/image-file-name.png). The rest of the wiki pages behave more intuitively. If you use use the plugin's link address completion then all these details are handled by the plugin.

Moving images and updating references

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.

Automatic changes to references for the moved images is only available in the enhanced version of the plugin, you can get a 30-day free trial here: idea-multimarkdown enhanced

To change all image references from the root wiki folder to the img sub-folder:

1. Select the wiki root folder of your project by clicking on it
2. Use the menu Edit > Find > Replace in path... or the shortcut for this operation
3. Type (\!\[.*\]\()([^: /]+)(\) for Text to find: text box, only images whose link does not contain spaces , colons : or slashes / will be changed.
4. Type $1img/$2$3 for Replace with: text box.
5. Set other options as per image below and hit Find.

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]]

Anchors are created automatically with spaces and non-alphanumeric characters changed - with consecutive dashes changed to a single one and all characters lowercase. GitHub is more fancy with its anchor naming and changes all non-alpha characters to -, keeping duplicates, and appending a numeric sequence to anchors that would otherwise be identical. matching GitHub's anchor generation is on the todo list.

You cannot have a wiki link with only an anchor link 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.