GitHub Flavored Markdown viewer plugin for Eclipse

GitHub Flavored Markdown viewer plugin for Eclipse

This project provides an Eclipse view which provides a reasonably accurate presentation of GithHub Flavored Markdown files.

Usage

After installation (see below), the viewer may be accessed in any of the following ways:

Execute menu Window -> Show View -> Other... and select entry GFM Support -> GFM Viewer. Then, when files with an extension of 

.md

 are
saved from an Eclipse editor, this view is updated as would be seen when browsing the file via the GitHub website.

When a markdown file is selected in any tree navigation view, then a Show in GFM view context menu entry
is provided which when activated will automatically open the view and display the formatted markdown content.

You may click internal and external hyperlinks in the presented web page, and then click the left and right arrow navigation icons in the top right of the view to navigate backwards and forward in the browsing history.

N.B. If non-ASCII characters are used in the markdown file, the current implementation assumes UTF-8character encoding, see also here.

Installation
from Update Site

In Eclipse, do the following:
Go to menu Help -> Install New Software... and in the resulting dialog click the Add... button to present a further dialog, and here enter 

GFM
Viewer

 as the Name and this link as the Location and press OK
Select the GFM Viewer category in the install view, and proceed to install the software in the usual manner accepting all defaults
Eclipse will prompt for a restart, accept this, then the GFM viewer is usable as documented above

Installation
from Source Code

The following build and install process can be followed to build the plugin locally should there be an issue with the update site:
Ensure you have Maven executables installed for your OS
Clone this project's repository to a convenient location (a path not containing special characters like space is advised)
In a shell or command window, change working directory to 

gfm_viewer/parent

,
and set enviroment variable 

JAVA_HOME

 to
point to an installed JDK 6+
Build the plugin by executing the command: 

mvn
clean package

Start your preferred Eclipse version in the normal way
In Eclipse, execute menu Help -> Install New Software... and in the resulting dialog click the Add...button to present a further dialog, and here enter 

GFM
Viewer (local)

 as the Name and click theLocal... button, then navigate to the directory 

gfm_viewer/update-site/target/site

 and
press OK
Select the GFM Viewer category in the install view, and proceed to install the software in the usual manner accepting all defaults
Eclipse will prompt for a restart, accept this, then the GFM viewer is usable as documented above

Uninstall

If desired, the GFM viewer plugin may be uninstalled via by selecting menu Help -> About Eclipse Platform
In the resulting dialog click button Installation Details, then select entry GFM Viewer, then click buttonUninstall... and proceed accepting all defaults
Provided the plugin was the last one installed, alternatively you can select the Installation History tab in the dialog, pick the previous history entry, and then click the Revert button

Configuration

The GFM viewer plugin should work adequately without further configuration, however its operation may be customised via menu Window -> Preferences -> GFM Viewer. On that dialog page, properties may be set as follows:
Use Temp dir: by default formatted HTML files are stored in the original markdown file's directory, thus enabling relative local links to images to work properly; select this option to instead have them in the user's temporary directory
API URL: specifies an alternate URL for GitHub API calls (typically for corporate users only)
Username/Password: a limit of 60 updates per hour is imposed by GitHub for unauthenticated usage of their markdown rendering API, so provide GitHub credentials in these fields to have this limit raised, see here for
background
Template File: an alternate HTML template file to the default may be provided
CSS URL 1-3: an alternate CSS presentation to the default may be provided
JS URL 1-3: an alternate JS implementation to the default may be provided

Regarding the temporary formatted HTML files, when stored in the original markdown file directory note:
You may wish to add the exclusion pattern 

.*.md.html

 to
your projects 

.gitignore

 file, which will
prevent their inclusion in version control operations
You can manage the visibility of these files in Eclipse tree views via the View menu (small triangle icon in top right of view), then select the Filters... entry, and then set or clear the .* resources check box

Implementation

The GFM Viewer Eclipse view part implementation is quite straight-forward, and operates as follows:
On construction, the view instantiates a web browser SWT component (which will be the default for the host OS, e.g. IE for Windows)
An event listener is registered which detects the opening and saving of markdown files in a relevant editor
When such an event is detected, then the editor's text contents are captured and sent to the GitHub rendering API resulting an an HTML segment
The resulting HTML segment is embedded in an HTML template to produce a standards conformant HTML document
The resulting HTML document is then sent to the browser component for display in the view
Updates to the viewed HTML document aim to preserve the current scroll position (via Javascript)

Development

If you want to do development on the plugin, proceed as follows:
You will need an Eclipse instance which does not have the GFM viewer installed, but does have the following PDE-related plugins installed (check via Help -> About Eclipse Platform -> Installation Details):
Eclipse Plug-in Development Environment
Eclipse RCP Plug-in Development Resources
Eclipse RCP SDK

If any of these are absent, you must install them from the relevant main Eclipse update site, e.g. forJuno
Ensure the Group items by category checkbox is unticked in the installer Available Software dialog, otherwise these plugins may be hard to find

Then you can proceed as follows:
In the PDE Eclipse started with a new workspace, it is advisable to use the Git Repositories view to clone the GitHub repo by pasting the GitHub URL as this will avoid line termination issues later
Then perform a simple (not Maven) import of all six directories below 

gfm_viewer

 as
existing Eclipse projects, namely 

ext-deps

, 

feature

, 

p2-repo

, 

parent

, 

plugin

,
and 

update-site

If necessary, via the context menu on the new projects, select Team -> Share Project... -> Git and click through accepting the defaults to connect the projects to version control
Via the context menu on projects 

ext-deps

 and 

parent

 only,
select Configure -> Convert to Maven Project
Create an Eclipse Maven run configuration for the GFM Viewer ext-deps project with goals

clean
package

 and workspace refresh, and then run it
Verify the last step created a jar file around 4Mb in size in the 

lib

 directory
of project GFM Viewer plugin
Create an Eclipse Application run configuration for the GFM Viewer plugin project, and then run it
If the child Eclipse instance has memory problems, consider adding 

-XX:MaxPermSize=128m

 to
the launch configuration JVM arguments
In the child instance, follow the usage instructions to show the GFM view
Additional debug information is available by editing the plugin run configuration, and on the dialog select the Tracing tab and then enable the entry for 

code.satyagraha.gfm.viewer.plugin

You can build all GFM project components with Tycho in Eclipse by creating a Maven build configuration in project GFM Viewer parent with goals 

clean
package

 and workspace refresh, ensuring that on theJRE tab an Alternate JRE is specified which refers to a full JDK. However, as the directory structure for Maven builds differs from that in Eclipse (by the using a 

target

 subdirectory)
this may be more confusing than useful.

You can create an update site in the traditional way as follows:
In the project GFM Viewer update site, open the file 

site.xml

On the presented editor's Site Map tab, click the Build All button, and the plugin, feature, and update site will be built
Verify that, in the update site project, directories 

features

 and 

plugins

 have
been created, containing jar files

An additional project GFM Viewer p2-repo is provided which is an experimental use of the Tycho P2 Repository generation facility, prompted by the deprecation
of the update site mechanism. After a Maven Tycho build you may select the directory 

gfm_viewer/p2-repo/target/repository

 as
a local update site as an alternative to the other one.

To Do

Areas possibly meriting further attention include:
It appears that GitHub may use some kind of dynamic CSS generation: the consequence is that the coverage provided by this plugin's simple static CSS may well not include some important entries (simply because they were not apparent on the test content used
in development).

Markdown
Editors

The Winterstein Eclipse Markdown Editor plugin is recommended as an excellent general markdown editor which complements this viewer
plugin well.

License

Eclipse Public License 1.0

History

1.0.0 - initial version
1.0.1 - use UTF-8 text encoding, e.g. 快乐 ハッピー ευτυχισμένος
1.1.0 - transformation done in background job, provide context menu, temp dir option
1.1.1 - added update site