Skip to content

Java API Reference v2.28.1

Package: dev.kreuzberg:html-to-markdown | Version: 2.28.1 | Java: 25+ (Panama FFI)

Installation

<dependency>
  <groupId>dev.kreuzberg</groupId>
  <artifactId>html-to-markdown</artifactId>
  <version>2.28.1</version>
</dependency>

implementation("dev.kreuzberg:html-to-markdown:2.28.1")

The package uses Java's Foreign Function & Memory API (Panama) to call the native Rust library. No JNI code required.

Class: HtmlToMarkdown

All methods are static on dev.kreuzberg.htmltomarkdown.HtmlToMarkdown.

convert

Convert HTML to Markdown using default options.

public static String convert(String html)
public static String convert(String html, ConversionOptions options)

Parameters:

Parameter Type Description
html String The HTML string to convert
options ConversionOptions Optional conversion options

Returns: String -- the converted Markdown.

Throws: HtmlToMarkdownException on conversion failure.

Example:

import dev.kreuzberg.htmltomarkdown.HtmlToMarkdown;
import dev.kreuzberg.htmltomarkdown.ConversionOptions;

String html = "<h1>Hello</h1><p>World</p>";
String markdown = HtmlToMarkdown.convert(html);

// With options
ConversionOptions options = new ConversionOptions()
    .setHeadingStyle("atx")
    .setWrap(true)
    .setWrapWidth(80);
String markdown = HtmlToMarkdown.convert(html, options);

convertWithMetadata

Convert HTML to Markdown with metadata extraction.

public static ConversionResult convertWithMetadata(String html)
public static ConversionResult convertWithMetadata(String html, ConversionOptions options)

Returns: ConversionResult -- object containing getMarkdown() and getMetadata().

Example:

ConversionResult result = HtmlToMarkdown.convertWithMetadata(html);
System.out.println(result.getMarkdown());

ExtendedMetadata metadata = result.getMetadata();
System.out.println(metadata.getDocument().getTitle());
System.out.println(metadata.getHeaders().size());
System.out.println(metadata.getLinks().size());

convertWithVisitor

Convert HTML with a custom visitor.

public static String convertWithVisitor(String html, Visitor visitor)
public static String convertWithVisitor(String html, Visitor visitor, ConversionOptions options)

Example:

import dev.kreuzberg.htmltomarkdown.visitor.Visitor;
import dev.kreuzberg.htmltomarkdown.visitor.VisitResult;

Visitor visitor = new Visitor() {
    @Override
    public VisitResult visitImage(NodeContext ctx, String src, String alt, String title) {
        return VisitResult.skip();
    }
};

String markdown = HtmlToMarkdown.convertWithVisitor(html, visitor);

version

Return the version string of the native library.

public static String version()

Classes

ConversionOptions

Built using the builder pattern.

ConversionOptions options = new ConversionOptions()
    .setHeadingStyle("atx")          // "underlined", "atx", "atxClosed"
    .setListIndentType("spaces")     // "spaces", "tabs"
    .setListIndentWidth(2)
    .setBullets("-")
    .setWrap(true)
    .setWrapWidth(80)
    .setPreserveTags(List.of("table", "div"))
    .setSkipImages(false)
    .setOutputFormat(OutputFormat.MARKDOWN);  // MARKDOWN, DJOT, PLAIN

See the Configuration Reference for all fields.

Visitor Interface

public interface Visitor {
    default VisitResult visitText(NodeContext ctx, String text) { return VisitResult.continueResult(); }
    default VisitResult visitLink(NodeContext ctx, String href, String text, String title) { return VisitResult.continueResult(); }
    default VisitResult visitImage(NodeContext ctx, String src, String alt, String title) { return VisitResult.continueResult(); }
    default VisitResult visitHeading(NodeContext ctx, int level, String text, String id) { return VisitResult.continueResult(); }
    default VisitResult visitCodeBlock(NodeContext ctx, String language, String code) { return VisitResult.continueResult(); }
    default VisitResult visitCodeInline(NodeContext ctx, String code) { return VisitResult.continueResult(); }
    default VisitResult visitListItem(NodeContext ctx, boolean ordered, String marker, String text) { return VisitResult.continueResult(); }
    default VisitResult visitTableRow(NodeContext ctx, String[] cells, boolean isHeader) { return VisitResult.continueResult(); }
    default VisitResult visitBlockquote(NodeContext ctx, String content, int depth) { return VisitResult.continueResult(); }
    default VisitResult visitStrong(NodeContext ctx, String text) { return VisitResult.continueResult(); }
    default VisitResult visitEmphasis(NodeContext ctx, String text) { return VisitResult.continueResult(); }
    default VisitResult visitElementStart(NodeContext ctx) { return VisitResult.continueResult(); }
    default VisitResult visitElementEnd(NodeContext ctx, String output) { return VisitResult.continueResult(); }
    // ... and more
}

VisitResult

public class VisitResult {
    public static VisitResult continueResult();
    public static VisitResult skip();
    public static VisitResult preserveHtml();
    public static VisitResult custom(String output);
    public static VisitResult error(String message);
}

Panama FFI Details

The Java binding uses the Foreign Function & Memory API (Project Panama) introduced in Java 25. Key implementation details:

  • Native library loaded via SymbolLookup and Linker.nativeLinker()
  • Memory managed through Arena scopes for automatic cleanup
  • String marshalling uses UTF-8 encoding via MemorySegment
  • No JNI code, header files, or generated stubs required

JVM flags (if needed):

--enable-native-access=ALL-UNNAMED

See Also