mikepenz/multiplatform-markdown-renderer

For multiplatform projects, add these dependencies to your build.gradle.kts:

dependencies {
    // Core library
    implementation("com.mikepenz:multiplatform-markdown-renderer:${version}")

    // Choose ONE of the following based on your Material theme:

    // For Material 2 themed apps
    implementation("com.mikepenz:multiplatform-markdown-renderer-m2:${version}")

    // OR for Material 3 themed apps
    implementation("com.mikepenz:multiplatform-markdown-renderer-m3:${version}")
}

For JVM-only projects, add this dependency:

dependencies {
    implementation("com.mikepenz:multiplatform-markdown-renderer-jvm:${version}")
}

For Android-only projects, add this dependency:

dependencies {
    implementation("com.mikepenz:multiplatform-markdown-renderer-android:${version}")
}

rememberMarkdownState

For better performance, especially with larger markdown content, use rememberMarkdownState or move the parsing of the markdown into your viewmodel:

val markdownState = rememberMarkdownState(markdown)
Markdown(markdownState)

[!NOTE]
Since version 0.33.0, markdown content is parsed asynchronously by default, resulting in a loading state being displayed prior to the parsing result. The rememberMarkdownState function offers the ability to require immediate parsing with the immediate parameter, but this is not advised as it might block the composition of the UI.

// Default asynchronous parsing (recommended)
val markdownState = rememberMarkdownState(markdown)

// Force immediate parsing (not recommended)
val markdownState = rememberMarkdownState(markdown, immediate = true)

Retaining State During Updates

By default, when the markdown content changes, the component shows a loading state while parsing the new content. You can use the retainState parameter to keep the previous rendered content visible while the new content is being parsed:

// Retain previous content during updates (avoids showing loading state)
val markdownState = rememberMarkdownState(
    markdown,
    retainState = true
)
Markdown(markdownState)

// With dynamic content loading
val markdownState = rememberMarkdownState(
    key, // key that triggers re-parsing
    retainState = true
) {
    "# Dynamic content $counter"
}
Markdown(markdownState)

This is particularly useful when content updates frequently or when you want to avoid flickering between the old content and the loading state.

Lazy Loading for Large Documents

Since version 0.33.0, the library supports rendering large markdown documents efficiently using LazyColumn instead of Column. This is particularly useful for very long markdown content.

Markdown(
    markdownState = markdownState,
    success = { state, components, modifier ->
        LazyMarkdownSuccess(state, components, modifier, contentPadding = PaddingValues(16.dp))
    },
    modifier = Modifier.fillMaxSize()
)

Parse Markdown in VM

[!NOTE]
This approach is also advised if you want to retain scroll position even when navigating away See: https://github.com/mikepenz/multiplatform-markdown-renderer/issues/374 Retaining state in the VM ensures parsing will not have to be done again, and the component can be immediately filled.

// In the VM setup the flow to parse the markdown
val markdownFlow = parseMarkdownFlow("# Markdown")
    .stateIn(lifecycleScope, SharingStarted.Eagerly, State.Loading())

// In the Composable use the flow
val state by markdownFlow.collectAsStateWithLifecycle()
Markdown(state)

Parse Markdown synchronously

If you want to pre-parse content before showing the UI and hand the result to Markdown without any Flow/StateFlow machinery, use parseMarkdown. It parses on the calling thread and returns the final, immutable State directly (State.Success on success, or State.Error on failure).

// Parse ahead of time and pass the already-parsed state to the Composable
val state = parseMarkdown("# Markdown")
Markdown(state)

[!NOTE]
Parsing happens on the calling thread. For large documents consider invoking this off the main thread.

The library offers the ability to modify different behaviour when rendering the markdown.

Provided custom style

Markdown(
    content,
    colors = markdownColor(text = Color.Red),
    typography = markdownTypography(h1 = MaterialTheme.typography.body1)
)

Disable Animation

By default, the MarkdownText animates size changes (if images are loaded).

Markdown(
    content,
    animations = markdownAnimations(
        animateTextSize = {
            this
            /** No animation */
        }
    ),
)

Extended spans

Starting with 0.16.0 the library includes support for extended-spans.

The library was integrated to make it multiplatform-compatible. All credits for its functionality go to Saket Narayan.

It is not enabled by default, however you can enable it quickly by configuring the extendedSpans for your Markdown composeable. Define the ExtendedSpans you want to apply (including optionally your own custom ones) and return it.

Markdown(
    content,
    extendedSpans = markdownExtendedSpans {
        val animator = rememberSquigglyUnderlineAnimator()
        remember {
            ExtendedSpans(
                RoundedCornerSpanPainter(),
                SquigglyUnderlineSpanPainter(animator = animator)
            )
        }
    }
)

Extend Annotated string handling

The library already handles a significant amount of different tokens, however not all. To allow special integrations expand this, you can pass in a custom annotator to the Markdown composeable. This annotator allows you to customize existing handled tokens, but also add new ones.

Markdown(
    content,
    annotator = markdownAnnotator { content, child ->
        if (child.type == GFMElementTypes.STRIKETHROUGH) {
            append("Replaced you :)")
            true // return true to consume this ASTNode child
        } else false
    }
)

Adjust List Ordering

// Use the bullet list symbol from the original markdown
CompositionLocalProvider(LocalBulletListHandler provides { type, bullet, index, listNumber, depth -> "$bullet " }) {
    Markdown(content)
}

// Replace the ordered list symbol with `A.)` instead.
CompositionLocalProvider(LocalOrderedListHandler provides { type, bullet, index, listNumber, depth -> "A.) " }) {
    Markdown(content, Modifier.fillMaxSize().padding(16.dp).verticalScroll(scrollState))
}

Custom Components

Since v0.9.0 it is possible to provide custom components, instead of the default ones. This can be done by providing the components MarkdownComponents to the Markdown composable.

Use the markdownComponents() to keep defaults for non overwritten components.

The MarkdownComponent will expose access to the content: String, node: ASTNode, typography: MarkdownTypography, offering full flexibility.

// Simple adjusted paragraph with different Modifier.
val customParagraphComponent: MarkdownComponent = {
    Box(modifier = Modifier.fillMaxWidth()) {
        MarkdownParagraph(it.content, it.node, Modifier.align(Alignment.CenterEnd))
    }
}

// Full custom paragraph example 
val customParagraphComponentComplex: MarkdownComponent = {
    // build a styled paragraph. (util function provided by the library)
    val styledText = buildAnnotatedString {
        pushStyle(LocalMarkdownTypography.current.paragraph.toSpanStyle())
        buildMarkdownAnnotatedString(it.content, it.node, annotatorSettings())
        pop()
    }

    // define the `Text` composable
    Text(
        styledText,
        textAlign = TextAlign.End
    )
}

// Define the `Markdown` composable and pass in the custom paragraph component
Markdown(
    content,
    components = markdownComponents(
        paragraph = customParagraphComponent // customParagraphComponentComplex
    )
)

Another example to of a custom component is changing the rendering of an unordered list.

// Define a custom component for rendering unordered list items in Markdown
val customUnorderedListComponent: MarkdownComponent = {
    // Use the MarkdownListItems composable to render the list items
    MarkdownListItems(it.content, it.node, depth = 0) { startNumber, index, child ->
        // Render an icon for the bullet point with a green tint
        Icon(
            imageVector = icon,
            tint = Color.Green,
            contentDescription = null,
            modifier = Modifier.size(20.dp),
        )
    }
}

// Define the `Markdown` composable and pass in the custom unorderedList component
Markdown(
    content,
    components = markdownComponents(
        unorderedList = customUnorderedListComponent
    )
)

Table Support

Starting with 0.30.0, the library includes support for rendering tables in markdown. The Markdown composable will automatically handle table elements in your markdown content.

val markdown = """
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |
""".trimIndent()

Markdown(markdown)

Alert Support

The library renders GitHub alerts — NOTE, TIP, IMPORTANT, WARNING and CAUTION — as an accent bar with an icon and a title.

val markdown = """
> [!NOTE]
> Useful information that users should know, even when skimming content.
""".trimIndent()

Markdown(markdown)

The accent colors, dimensions and paddings are grouped into dedicated models, the title style is exposed via markdownTypography(alertTitle = ...):

Markdown(
    markdown,
    colors = markdownColor(alert = markdownAlertColors(note = Color.Blue)),
    dimens = markdownDimens(alert = markdownAlertDimens(barThickness = 2.dp)),
    padding = markdownPadding(alert = markdownAlertPadding(iconSpacing = 12.dp)),
)

The icons are swappable via LocalMarkdownAlertIcons:

CompositionLocalProvider(
    LocalMarkdownAlertIcons provides markdownAlertIcons(note = Icons.Outlined.Info)
) {
    Markdown(markdown)
}

To fully replace the rendering, override the alert component through markdownComponents().