markdown

Introduction to IntelliJ-Markdown

IntelliJ-Markdown is an impressive Markdown processor written in the Kotlin programming language. Aimed at versatility and consistency, this processor is designed to function across multiple platforms, ensuring that developers have a single code base that can operate on both client and server sides. Here's an in-depth look at what IntelliJ-Markdown offers and how it can be utilized in various development environments.

Core Features

• Multiplatform Support: IntelliJ-Markdown is compatible with JVM, JS, and Native targets, thanks to its pure Kotlin foundation. This broad compatibility ensures that the same processor can be used across different environments without the need for modifications.
• Markdown Flavours: The processor supports multiple Markdown flavours, allowing developers to choose or extend the Markdown syntax to meet specific needs.
• Extensibility: The design of IntelliJ-Markdown emphasizes ease of extension, making it a flexible tool for developers who may need to incorporate additional functionalities.

How to Use IntelliJ-Markdown

Adding IntelliJ-Markdown as a Dependency

To start using IntelliJ-Markdown, you must add it as a dependency in your project. It's available in the Maven Central Repository, and the following snippets demonstrate how to include it in projects based on Gradle or Maven:

For Gradle (version 5.4 or later):

repositories {
  mavenCentral()
}

dependencies {
  implementation("org.jetbrains:markdown:<version>")
}

For multiplatform projects:

commonMain {
  dependencies {
    implementation("org.jetbrains:markdown:<version>")
  }
}

For Maven or older Gradle versions, specify the correct artifact for your platform, such as using org.jetbrains:markdown-jvm for JVM.

Parsing and Generating HTML

IntelliJ-Markdown is capable of parsing Markdown text and generating HTML. This function can be beneficial for various applications, such as syntax highlighting or document previews. Here are examples for simple HTML generation:

Kotlin Example:

val src = "Some *Markdown*"
val flavour = CommonMarkFlavourDescriptor()
val parsedTree = MarkdownParser(flavour).buildMarkdownTreeFromString(src)
val html = HtmlGenerator(src, parsedTree, flavour).generateHtml()

Java Example:

final String src = "Some *Markdown*";
final MarkdownFlavourDescriptor flavour = new GFMFlavourDescriptor();
final ASTNode parsedTree = new MarkdownParser(flavour).buildMarkdownTreeFromString(text);
final String html = new HtmlGenerator(src, parsedTree, flavour, false).generateHtml();

Development Considerations

Flex Lexer Definitions

Although primarily written in Kotlin, IntelliJ-Markdown utilizes .flex lexer definitions to generate parsers for Markdown inline elements. Due to some issues with java->kt conversion, manual steps are required to convert these lexers into Kotlin files. By using plugins like Grammar Kit and jflexToKotlin, you can automate and simplify this process.

Parsing Algorithm

The parsing process involves two main parts:

1. Logical Structure Building: Splitting the document into blocks such as lists and paragraphs.
2. Inline Parsing: Token processing and handling overlapping inline constructs according to priorities.

For comprehensive parsing, the project implements the strategy outlined in the CommonMark specification.

Generating HTML

Post parsing, HTML generation is facilitated using an AST root. A special visitor processes the tree and generates HTML by mapping nodes through the visitor pattern. Developers can customize this process using different Markdown flavours.

Extending the Parser

To extend IntelliJ-Markdown, you can create custom Markdown flavours based on classes like MarkdownFlavourDescriptor. This approach allows for unique Markdown features or adaptations of existing ones, like GitHub Flavored Markdown (GFM).

API Overview

The API consists of several classes and methods that provide comprehensive customizing capabilities:

• MarkdownFlavourDescriptor for base parser extensions.
• MarkerProcessorFactory for block structure management.
• SequentialParserManager for inline parsing procedures.
• Customized HTML generation by utilizing GeneratingProvider.

Overall, IntelliJ-Markdown is an extraordinarily adaptable processor suited for various applications requiring Markdown parsing and HTML generation, enrichening development capabilities across different platforms.