previewer-eclipse-plugin

Feedback and high-quality pull requests are highly welcome!

1. What is it?
2. Installation
3. Adding support for other formats
4. Building from Sources
5. Acknowledgement
6. License

What is it?

This extensible EclipseⓇ plugin contributes a new Preview view that displays rendered versions of files opened in text editors.

The following formats are supported out of the box:

• Draw.io diagrams
• GitHub flavored Markdown (GFM)
• GraphViz DOT diagrams
• HTML
• Mermaid diagrams
• PlantUML diagrams
• Scalable Vector Graphics (SVG)

This plugin is best used together with the TM4E incl. Language Pack and Extra Syntax Highlighting Plugin which provide syntax highlighting for the supported source files.

• Markdown example:

  

• GraphViz example:

  

Installation

To install the plugin into an existing Eclipse installation do:

1. Within Eclipse go to: Help -> Install New Software...
2. Enter the following update site URL: https://raw.githubusercontent.com/sebthom/previewer-eclipse-plugin/updatesite
3. Select the Previewer feature to install.
4. Ensure that the option Contact all update sites during install to find required software is enabled.
5. Click Next twice.
6. Read/accept the license terms and click Finish.
7. Eclipse will now download the necessary files in the background.
8. When the download has finished, Eclipse will ask about installing unsigned content. You need to accept if you want to
9. After installation you will be prompted for a restart of Eclipse, which is recommended.

Adding support for other formats

The plugin provides extension points that allow registration of additional renderers to support more file formats. If you are new to Eclipse plugin development please consult https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/FAQ/FAQ_What_are_extensions_and_extension_points.md for more details about extension points.

1. The htmlPreviewerRenderer extension point allows to register classes implementing de.sebthom.eclipse.previewer.api.HtmlPreviewRenderer: HtmlPreviewRenderer are used to render source files to a HTML representation. The renderer plugin display the generated HTML inside managed browser component.

   <extension point="de.sebthom.eclipse.previewer.renderers">
      <htmlPreviewRenderer class="com.example.ConfigHtmlPreviewRenderer" file-extensions="cfg,ini" file-pattern="**/.cfg/_config_rc" file-names="CONFIG_RC" />
   </extension>

2. The previewerRenderer extension point allows to register classes implementing de.sebthom.eclipse.previewer.api.PreviewRenderer: If rendering to HTML is not desirable or possible PreviewRenderers can be used to render source files onto an SWT Composite managed by the renderer itself.

   <extension point="de.sebthom.eclipse.previewer.renderers">
      <previewRenderer class="com.example.ConfigPreviewRenderer" file-extensions="cfg,ini" file-pattern="**/.cfg/_config_rc" file-names="CONFIG_RC" />
   </extension>

Building from Sources

To ensure reproducible builds this Maven project inherits from the vegardit-maven-parent project which declares fixed versions and sensible default settings for all official Maven plug-ins.

The project also uses the maven-toolchains-plugin which decouples the JDK that is used to execute Maven and it's plug-ins from the target JDK that is used for compilation and/or unit testing. This ensures full binary compatibility of the compiled artifacts with the runtime library of the required target JDK.

To build the project follow these steps:

1. Download and install a Java 17 SDK, e.g. from:

   • https://adoptium.net/releases.html?variant=openjdk17
   • https://www.azul.com/downloads/?version=java-17-lts&architecture=x86-64-bit&package=jdk

2. Download and install the latest Maven distribution.

3. In your user home directory create the file .m2/toolchains.xml with the following content:

   <?xml version="1.0" encoding="UTF8"?>
   <toolchains>
      <toolchain>
         <type>jdk</type>
         <provides>
            <version>17</version>
            <vendor>default</vendor>
         </provides>
         <configuration>
            <jdkHome>[PATH_TO_YOUR_JDK_17]</jdkHome>
         </configuration>
      </toolchain>
   </toolchains>

   Set the [PATH_TO_YOUR_JDK_17] parameter accordingly.

4. Checkout the code using one of the following methods:

   • git clone https://github.com/sebthom/previewer-eclipse-plugin
   • svn co https://github.com/sebthom/previewer-eclipse-plugin previewer-eclipse-plugin

5. Run mvn clean verify in the project root directory. This will execute compilation, unit-testing, integration-testing and packaging of all artifacts.

Acknowledgement

Draw.io diagrams are rendered using https://www.draw.io/js/viewer.min.js, which is licensed under Apache License 2.0 .

By default, GraphViz DOT files are rendered using a bundled version of Viz.js, which is licensed under MIT.

By default, Markdown files are rendered using a bundled version of CommonMark Java, which is licensed under BSD-2-Clause.

Rendered Markdown files are styled using GitHub MarkDown CSS, which is licensed under MIT.

Mermaid files are rendered using a bundled version of Mermaid JS, which is licensed under MIT.

PlantUML files are rendered using a bundled version of PlantUML, which is licensed under MIT

License

If not otherwise specified (see below), files in this repository fall under the Eclipse Public License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: EPL-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.

An exception is made for:

1. files in readable text which contain their own license information, or
2. files in a directory containing a separate LICENSE.txt file, or
3. files where an accompanying file exists in the same directory with a .LICENSE.txt suffix added to the base-name of the original file. For example foobar.js is may be accompanied by a foobar.LICENSE.txt license file.