Skip to content

JVM port of graceful markdown processor marked.js

License

Notifications You must be signed in to change notification settings

gitbucket/markedj

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

markedj build Maven Central License

JVM port of graceful markdown processor marked.js.

Usage

First, add following dependency into your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.github.gitbucket</groupId>
    <artifactId>markedj</artifactId>
    <version>1.0.20</version>
  </dependency>
</dependencies>

You can easily use markedj via io.github.gitbucket.markedj.Marked:

import io.github.gitbucket.markedj.*;

String markdown = ...

// With default options
String html1 = Marked.marked(markdown);

// Specify options
Options options = new Options();
options.setSanitize(true);

String html2 = Marked.marked(markdown, options);

Options

io.github.gitbucket.markedj.Options has following properties to control Markdown conversion:

Name Default Description
gfm true Enable GitHub Flavored Markdown.
tables true Enable GFM tables. This option requires the gfm option to be true.
breaks false Enable GFM line breaks. This option requires the gfm option to be true.
sanitize false Ignore any HTML that has been input.
langPrefix "lang-" Prefix of class attribute of code block
headerPrefix "" Prefix of id attribute of header
safelist See Options.java Safelist of HTML tags.
extensions empty Extensions. See Extensions section

By default, markedj uses Jsoup's safelist mechanism for HTML rendering. It restricts renderable tags, attributes and even protocols of attribute values. For example, the image url must be http:// or https:// by default. You can remove this restriction by customizing the safelist as follows:

String html1 = Marked.marked("![alt text](/img/some-image.png \"title\")");
  // => <p><img alt=\"alt text\" title=\"title\"></p>

Options options = new Options();
options.getSafelist().removeProtocols("img", "src", "http", "https");

String html2 = Marked.marked("![alt text](/img/some-image.png \"title\")", options);
  // => <p><img src="/img/some-image.png" alt="alt text" title="title"></p>

Extensions

Markedj can be extended by implementing custom extensions. Extensions can be used by adding them to the options.

Options options = new Options();
options.addExtension(new GFMAlertExtension());
String html = Marked.marked("> [!NOTE]\n> This is a note!", options);

GFMAlert extension

Support for github like alerts.

For styling, some project-specific CSS is required.

Options options = new Options();
// Override default title for note alert
GFMAlertOptions alertOptions = new GFMAlertOptions();
alertOptions.setTitle(GFMAlerts.Alert.WARNING, "Attention!!!");
GFMAlertExtension gfmAlerts = new GFMAlertExtension(alertOptions);
options.addExtension(gfmAlerts);
String html = Marked.marked("> [!NOTE]\n> This is a note!", options);

Supported alert types are NOTE, TOP, IMPORTANT, WARNING, and CAUTION. Here is a Markdown example:

> [!NOTE]
> Useful information that users should know, even when skimming content.

This is translated to the following HTML:

<div class="markdown-alert markdown-alert-note">
  <p class="markdown-alert-title">Note</p>
  <p>Useful information that users should know, even when skimming content.</p>
</div>

Generated HTML can be customized by implementing your own renderer. DefaultGFMAlertRenderer is used by default.

for Developers

Release

Run the following command to upload artifacts to sonatype:

mvn clean deploy -DperformRelease=true

Then, go to https://oss.sonatype.org/, close and release the staging repository.