GitHub Flavored Markdown Viewer plugin for Eclipse

<a href="http://marketplace.eclipse.org/marketplace-client-intro?mpc_install=900708" title="Drag and drop into a running Eclipse to install GitHub Flavored Markdown viewer plugin">

satyagraha: Nodeclipse:

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

It is also new way to create Eclipse plugin help contents.

See installation options and version history below.

Usage

Note: Usage & Configuration were copied into built-in Help. When changing please delete here and add links into plugin/src/site/markdown

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.

• When one or more directories and/or markdown files are selected in any tree navigation view, then a Generate Markdown Preview context menu entry is presented which when activated will regenerate all associated markdown preview files (via background jobs recursively traversing the directory trees): this is effectively a batch mode update facility.

• The GFM plugin view provides on its toolbar the following icons which may be clicked:

  • - show preferences page
  • - on/off-line mode, switch off when not connected to internet
  • - linked mode, use to keep GFM View aligned with active editor
  • - reload, to manually update GFM View from last linked file
  • - navigate backwards in the browsing history
  • - navigate forwards in the browsing history

The On/Off-line and Editor linked modes are by default on, but if set off their state will be automatically saved and preserved in the Eclipse workspace provided the GFM view is not closed.

When operating in Off-line mode, if the local cached HTML version of the markup file is out-of-date with respect to the markdown file, then the title bar of the browser has a '*' character preceding the file name, similar to the "dirty" indicator in editors.

The plugin uses Eclipse's default browser, e.g. Internet Explorer on Windows; if you use Ubuntu or other Linux distros, we recommend the WebKit browser; see:

• http://www.eclipse.org/swt/faq.php#browserlinuxrcp
• http://www.eclipse.org/swt/faq.php#browserlinux

If you want to view two (or more) markdown files simultaneously, simply open a new Eclipse window via menu Window -> New Window and there open another instance of the viewer: then any markdown files edited in that window will display in that window's viewer, independently of the original window and its editors and viewer.

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

Configuration

The GFM viewer plugin should work adequately without further configuration, however its operation may be customized 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
• Use Eclipse Console: shows debugging output in Console view
• Markdown Extensions: recognized markdown extensions

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

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 alter the checkbox settings there as necessary
• 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 of Alternate Versions

The above installation mechanism will install the latest official version of the plugin. It is possible to install older or newer beta versions of the software by using http://dl.bintray.com/satyagraha/generic/x.y.z as the update site URL, where x.y.z is the desired version. You can see the available versions at http://dl.bintray.com/satyagraha/generic/.

Installation from Source Code

Should there be an issue with the update site, the following build and install process can be followed to build the plugin locally assuming a typical Windows 7+ environment:

• Ensure you have Maven executables installed for your OS and enviroment variable JAVA_HOME points to an installed 32-bit JDK 8+ (see Development section below
• 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 project root ( gfm_viewer with this README.md),
• Build the plugin by executing the command: mvn clean package
• If building under Linux, take a look at the .travis.yml file in the base directory to see any additional browser-related requirements
• 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 the Local... 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 button Uninstall... 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

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 in 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, the following steps outline the process for a Windows 7+ development environment:

• download and install a 32-bit Sun Java JDK SE8uX from http://www.oracle.com/technetwork/java/javase/downloads/index.html
• download and unzip a 32-bit Eclipse for RCP and RAP Developers from http://www.eclipse.org/downloads/ (Mars version 4.5.2 recommended)
• edit the eclipse.ini of the new Eclipse installation, setting its' -vm value to the installed 32-bit JDK folder path as in https://wiki.eclipse.org/Eclipse.ini#-vm_value:_Windows_Example

Then you can proceed as follows:

• In the new Eclipse started with a new workspace, do Window -> Preferences -> Maven -> Discovery, select Open Catalog and enter Tycho in the find filter box; when a result entitled Tycho Configurator is located, proceed to install it in the usual way, with IDE restart
• In the Git Repositories view, clone the GitHub repo by pasting the GitHub URL as this will avoid line termination issues later
• Then switch to the Plug-in Development perspective, then activate the context menu in the Package Explorer panel and select entry Import -> Maven -> Existing Maven Projects and navigate to the top-level project clone folder
• Click through and accept all the defaults to complete the import process
• If necessary (e.g. before EGit 3.0), 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
• Create an Eclipse Maven run configuration for the GFM Viewer parent project with goals clean integration-test 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, although there will still be build errors at this point
• Expand the GFM Viewer plugin child project and open its plugin.xml file, select the Overview tab and click the Update the classpath settings link; the projects should now build successfully
• Create an Eclipse Application run configuration for the GFM Viewer plugin project, on the Plug-ins tab click Add Required Plugins, and then run it
• 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 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.

In order to update version:

mvn -Dtycho.mode=maven org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=1.X.0

Make sure to do a search through all files to find any occurrences of the old version, as they will be present in some Eclipse plugin manifest and build properties files.

The repository has Travis CI configured (see buttons about), so every commit will be built and the result seen.

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

Acknowledgements

• Thanks to Paul Verest for sustained input into this project
• Thanks to Olivier Laviale for CSS contributions
• The Picocontainer dependency injection framework works well inside the Eclipse 3.x environment, and makes object management far easier than otherwise
• The EventBus library provides a neat loosely coupled publish/subscribe framework
• The ObjectAid Eclipse plugin allows one easily to create UML class diagrams as an aid to understanding the relationships between the entities
• The ispace Eclipse plugin creates a dependency graph of packages and classes in a project, highlighting circular dependencies which typically indicate poor design
• For Java unit testing, Mockito is superb
• For Eclipse UI testing, SWTBot works pretty well

History

• 2.0.1 - Fix GH prefix; refresh tooling versions
• 1.9.3 - Updated CSS; require JVM 1.7
• 1.9.2 - Add null test to HTML template
• 1.9.1 - Remove GitHub anchor name prefixes
• 1.9.0 - Web proxy fixes
• 1.8.5 - Web proxy support beta
• 1.8.4 - Support Eclipse proxy settings
• 1.8.3 - Fix broken release
• 1.8.2 - Minor fixes and feature improvements
• 1.8.1 - UI tests, fixes
• 1.8.0 - On/Off-line mode
• 1.7.0 - Various fixes, Ubuntu supported via Webkit browser
• 1.6.0 - Skip HTML regeneration by default, fixes
• 1.5.0 - Help page how to add Help to an Eclipse plugin, console logging
• 1.4.0 - hierarchical project structure, dependency injection, built-in Help, fix NPE when changing perspective
• 1.3.0 - filtered links, batch mode, and bintray update site
• 1.2.1 - fix update site link
• 1.2.0 - link with editor/reload option, tests module
• 1.1.1 - added update site
• 1.1.0 - transformation done in background job, provide context menu, temp dir option
• 1.0.1 - use UTF-8 text encoding, e.g. 快乐 ハッピー ευτυχισμένος
• 1.0.0 - initial version