Writing in plain text has its own charm, but what if you could format your text without using complex editors or software? Enter Markdown, a language designed to enhance plain text formatting without complicating your workflow. Engineers, especially those working with Java and needing to document their work, find Markdown extremely useful.

In this tutorial, we are set to explore some top examples of using Markdown in Java. Before we start, note that the examples work for both Standard Markdown and GitHub Flavored Markdown.

Introduction to Markdown

Markdown is a lightweight markup language that provides a simplistic way to format text. It includes elements such as headers, links, bold and italic text, lists, block quotes, and code blocks.

In Java ecosystem, there are several libraries that can parse Markdown, but for this guide, we’ll use ‘flexmark-java’, a popular and flexible Markdown processor.

Setting Up a Java Markdown Parser

A markdown parser translates Markdown text into another format like HTML. To set up ‘flexmark-java’ in your project, add the following dependency to your pom.xml file.

<dependency>
    <groupId>com.vladsch.flexmark</groupId>
    <artifactId>flexmark-all</artifactId>
    <version>0.35.10</version>
</dependency>

Next, import the necessary classes for parsing Markdown.

import com.vladsch.flexmark.html.HtmlRenderer;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.util.ast.Document;

Now, you are well-prepared to parse any Markdown text into HTML.

Read more about FlexMark on the GitHub page

Markdown Syntaxes with Java Examples

Let’s dive into some common Markdown syntaxes with their Java implementation.

Headers

In Markdown, headers are created by using hash (#) symbols before your text. There can be up to six levels of headers, ranging from one hash for the largest header to six hashes for the smallest.

Markdown Input

# This is an H1
## This is an H2
###### This is an H6

To parse this input into HTML using Java, use the following code.

String markdownInput = "# This is an H1\n## This is an H2\n###### This is an H6";
Parser parser = Parser.builder().build();
Document document = parser.parse(markdownInput);
HtmlRenderer renderer = HtmlRenderer.builder().build();
System.out.println(renderer.render(document));

Expected HTML Output

<h1>This is an H1</h1>
<h2>This is an H2</h2>
<h6>This is an H6</h6>

Emphasis

In Markdown, you can create italic and bold text by using asterisk (*) or underscore (_).

Markdown Input

*This text will be italic*
**This text will be bold**

Now, let’s parse this into HTML.

String markdownInput = "*This text will be italic*\n**This text will be bold**";
Document document = parser.parse(markdownInput);
System.out.println(renderer.render(document));

Expected HTML Output

<p><em>This text will be italic</em></p>
<p><strong>This text will be bold</strong></p>

…and so forth. The scope of Markdown syntax is vast, also including lists, links, images, and many fancy elements. Knowing how to use Markdown offers numerous advantages, including writing documentation, notes, and even formatting content on platforms like GitHub.

Don’t hesitate to explore more features of Markdown and flexmark-java. As they say, practice is key, so let’s grab a coffee, code, and write beautiful Markdown!