If you have ever built a Java application that converts Markdown to HTML—whether for a blog engine, a documentation site, or user-generated comments—you have likely run into a frustrating roadblock.

You pull in a solid library like commonmark-java, pass your Markdown string, and get perfectly valid semantic HTML blocks. But then you render it on the frontend and realize it looks completely unstyled.

Modern CSS frameworks like Tailwind CSS, Bootstrap, or Bulma rely heavily on utility classes. They don't automatically style raw <h1>, <p>, or <blockquote> tags unless you wrap them in heavy global stylesheet overrides. To fix this in Java, you are usually forced to write verbose custom tag renderers, map complex attribute providers, or write messy string-replacement wrappers.

That is exactly the problem FluentMarkdown solves.

💡 What is FluentMarkdown?

FluentMarkdown is a lightweight, zero-boilerplate Java library built directly on top of commonmark-java. It introduces a clean, fluent API that automatically injects the proper CSS framework classes into your HTML elements during the parsing phase.

Instead of fighting your CSS framework, you can map your tags instantly using built-in presets or completely custom styles.

🛠️ Getting Started

1. Installation

The library is explicitly lightweight (only four core files) and requires Java 17 or later. You can add it via Maven:

<dependency>
    <groupId>io.github.gaurav101</groupId>
    <artifactId>fluentmarkdown</artifactId>
    <version>1.0.4</version>
</dependency>

2. Quick Start: Use a Framework Preset

If you use Tailwind, Bootstrap 5, or Bulma, FluentMarkdown has pre-mapped configurations ready to go.

Here is how easily you can render fully-styled Tailwind HTML:

import io.github.gaurav101.fluentmarkdown.Markdown;

public class App {
    public static void main(String[] args) {
        String markdown = "# Hello World\nThis is a paragraph.";

        // One fluent chain handles it all
        String tailwindHtml = Markdown.from(markdown)
                                      .withTailwind()
                                      .toHtml();

        System.out.println(tailwindHtml);
    }
}

Output:

<h1 class="text-4xl font-extrabold tracking-tight mb-4 mt-6">Hello World</h1>
<p class="mb-4 leading-relaxed text-base">This is a paragraph.</p>

Switching frameworks is as simple as swapping .withTailwind() for .withBootstrap() or .withBulma().

🧠 Advanced Usage

🔒 Step 3: XSS Protection (Safe Mode)

If you are processing untrusted user input (like blog comments), rendering raw HTML can expose your app to Cross-Site Scripting (XSS) attacks. FluentMarkdown includes a built-in .safe() modifier that strips out malicious inline scripts and raw HTML blocks seamlessly.

String unsafeInput = "<script>alert('hack')</script>\n\n# Safe Title";

String safeHtml = Markdown.from(unsafeInput)
                          .withTailwind()
                          .safe() // Strips dangerous HTML
                          .toHtml();

🎨 Step 4: Custom Style Configurations

Don't use a standard CSS framework? You can build an immutable StyleConfig to map your own internal design system classes to any HTML tag.

import io.github.gaurav101.fluentmarkdown.StyleConfig;

StyleConfig myCustomConfig = StyleConfig.builder()
        .tag("h1", "custom-main-title")
        .tag("p", "body-text text-muted")
        .tag("a", "global-link")
        .build();

String customHtml = Markdown.from(markdown)
                            .withStyle(myCustomConfig)
                            .toHtml();

🔄 Step 5: Extend Existing Presets

If you love the Tailwind preset but want to tweak just one or two elements (like changing the link color), you can merge and overwrite tags dynamically:

import io.github.gaurav101.fluentmarkdown.Presets;

StyleConfig modifiedTailwind = StyleConfig.builder()
        .mergeFrom(Presets.tailwind()) // Start with Tailwind defaults
        .tag("a", "text-indigo-600 underline") // Overwrite just the anchor tag
        .build();

🎯Conclusion

FluentMarkdown provides a highly practical solution to a common backend UI problem. It keeps your Java code clean, readable, and perfectly married to modern frontend utilities.

Give the project a look, try it out in your next Java project, and don't forget to drop a ⭐️ on the repository!

👉 GitHub Repository: gaurav101/FluentMarkdown