wtslh/gfm_viewer

An Eclipse plugin providing an accurate view of GitHub Flavored Markdown (.md) files

GitHub Flavored Markdown Viewer plugin for Eclipse

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. Check project sources and developer instructions at GitHub https://github.com/satyagraha/gfm_viewer .

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

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 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 and enviroment variable JAVA_HOME points to an installed JDK 6+
• 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 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:

• get fresh new Eclipse Standard from http://www.eclipse.org/downloads/, or

• 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. for Kepler

• 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 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 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, 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, 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 the JRE 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.

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

History

• 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