GitHub Flavored Markdown viewer plugin for Eclipse

悠悠 2022-01-13 03:29 181阅读 0赞

# 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-8][]character 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 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

## 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][here 1] 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. for[Juno][]
 *  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][above] 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.

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

[GithHub Flavored Markdown]: http://github.github.com/github-flavored-markdown/
[context menu]: http://en.wikipedia.org/wiki/Context_menu
[UTF-8]: http://en.wikipedia.org/wiki/UTF-8
[here]: http://www.martinahrer.at/2007/06/03/eclipse-encoding-settings/
[link]: https://googledrive.com/host/0B2imkYUgmO5lWnpXMEhkZWdsWkU
[above]: https://github.com/satyagraha/gfm_viewer#usage
[Maven]: http://maven.apache.org/
[here 1]: http://developer.github.com/v3/#rate-limiting
[Juno]: http://download.eclipse.org/releases/juno
[deprecation of the update site mechanism]: http://wiki.eclipse.org/Tycho/Reference_Card#Update_Site
[Winterstein Eclipse Markdown Editor]: https://github.com/winterstein/Eclipse-Markdown-Editor-Plugin