Merge pull request #592 from mikepenz/develop

mikepenz · web-flow · commit c2e39dac89e8 · 2026-06-22T21:30:12.000+02:00
dev -&gt; main
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,6 +1,6 @@
 {
   "name": "Java",
-  "image": "mcr.microsoft.com/devcontainers/java:3-21@sha256:1e8bc687983da0d516d1c8d53c15abef59a5c83c0e829331ba145d9910ff4d9c",
+  "image": "mcr.microsoft.com/devcontainers/java:3-21@sha256:53e4659f8ca8d859366fa0f9bf2d0a56c334a07635e03d26fb6cba2d0885f6c7",
   "features": {
     "ghcr.io/devcontainers/features/java:1": {
       "version": "none",
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -33,7 +33,7 @@ jobs:
         run: mkdir -p ~/.gradle ; cp .github/ci-gradle.properties ~/.gradle/gradle.properties
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
 
       - name: Cache konan
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
@@ -79,13 +79,13 @@ jobs:
             21
 
       - name: Validate gradle wrapper
-        uses: gradle/actions/wrapper-validation@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        uses: gradle/actions/wrapper-validation@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
 
       - name: Copy CI gradle.properties
         run: mkdir -p ~/.gradle ; cp .github/ci-gradle.properties ~/.gradle/gradle.properties
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
 
       - name: Build Debug
         run: |
diff --git a/.github/workflows/gradle-dependency-submission.yml b/.github/workflows/gradle-dependency-submission.yml
@@ -24,6 +24,6 @@ jobs:
         run: mkdir -p ~/.gradle ; cp .github/ci-gradle.properties ~/.gradle/gradle.properties
 
       - name: Setup Gradle & Submit dependency graphs
-        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
         with:
           dependency-graph: generate-and-submit
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
@@ -40,7 +40,7 @@ jobs:
             17
             21
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
       - name: Build Page
         run: |
           ./gradlew sample:web:wasmJsBrowserDistribution --no-configuration-cache
diff --git a/README.md b/README.md
@@ -224,6 +224,22 @@ 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).
+
+```kotlin
+// 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
diff --git a/gradle.properties b/gradle.properties
@@ -1,7 +1,7 @@
 # Maven stuff
 GROUP=com.mikepenz
-VERSION_NAME=0.42.0
-VERSION_CODE=4200
+VERSION_NAME=0.43.0
+VERSION_CODE=4300
 #
 POM_URL=https://github.com/mikepenz/multiplatform-markdown-renderer
 POM_SCM_URL=https://github.com/mikepenz/multiplatform-markdown-renderer
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,6 +1,6 @@
 [versions]
 androidx-activityCompose = "1.13.0"
-coil = "3.4.0"
+coil = "3.5.0"
 coil2 = "2.7.0"
 markdown = "0.7.5"
 ktor = "3.5.0"
diff --git a/multiplatform-markdown-renderer/api/android/multiplatform-markdown-renderer.api b/multiplatform-markdown-renderer/api/android/multiplatform-markdown-renderer.api
@@ -608,6 +608,8 @@ public abstract interface class com/mikepenz/markdown/model/MarkdownState {
 public final class com/mikepenz/markdown/model/MarkdownStateKt {
 	public static final fun asMarkdownState (Lkotlinx/coroutines/flow/Flow;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun asMarkdownState$default (Lkotlinx/coroutines/flow/Flow;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun parseMarkdown (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lcom/mikepenz/markdown/model/State;
+	public static synthetic fun parseMarkdown$default (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lcom/mikepenz/markdown/model/State;
 	public static final fun parseMarkdownFlow (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun parseMarkdownFlow$default (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun rememberMarkdownState (Ljava/lang/String;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ZLandroidx/compose/runtime/Composer;II)Lcom/mikepenz/markdown/model/MarkdownState;
diff --git a/multiplatform-markdown-renderer/api/jvm/multiplatform-markdown-renderer.api b/multiplatform-markdown-renderer/api/jvm/multiplatform-markdown-renderer.api
@@ -678,6 +678,8 @@ public abstract interface class com/mikepenz/markdown/model/MarkdownState {
 public final class com/mikepenz/markdown/model/MarkdownStateKt {
 	public static final fun asMarkdownState (Lkotlinx/coroutines/flow/Flow;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun asMarkdownState$default (Lkotlinx/coroutines/flow/Flow;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun parseMarkdown (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lcom/mikepenz/markdown/model/State;
+	public static synthetic fun parseMarkdown$default (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lcom/mikepenz/markdown/model/State;
 	public static final fun parseMarkdownFlow (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun parseMarkdownFlow$default (Ljava/lang/String;ZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun rememberMarkdownState (Ljava/lang/String;ZZLorg/intellij/markdown/flavours/MarkdownFlavourDescriptor;Lorg/intellij/markdown/parser/MarkdownParser;Lcom/mikepenz/markdown/model/ReferenceLinkHandler;ZLandroidx/compose/runtime/Composer;II)Lcom/mikepenz/markdown/model/MarkdownState;
diff --git a/multiplatform-markdown-renderer/api/multiplatform-markdown-renderer.klib.api b/multiplatform-markdown-renderer/api/multiplatform-markdown-renderer.klib.api
@@ -921,6 +921,7 @@ final fun com.mikepenz.markdown.model/markdownDimens(androidx.compose.ui.unit/Dp
 final fun com.mikepenz.markdown.model/markdownExtendedSpans(kotlin/Function2<androidx.compose.runtime/Composer, kotlin/Int, com.mikepenz.markdown.compose.extendedspans/ExtendedSpans>?, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int): com.mikepenz.markdown.model/MarkdownExtendedSpans // com.mikepenz.markdown.model/markdownExtendedSpans|markdownExtendedSpans(kotlin.Function2<androidx.compose.runtime.Composer,kotlin.Int,com.mikepenz.markdown.compose.extendedspans.ExtendedSpans>?;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
 final fun com.mikepenz.markdown.model/markdownInlineContent(kotlin.collections/Map<kotlin/String, androidx.compose.foundation.text/InlineTextContent>?, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int): com.mikepenz.markdown.model/MarkdownInlineContent // com.mikepenz.markdown.model/markdownInlineContent|markdownInlineContent(kotlin.collections.Map<kotlin.String,androidx.compose.foundation.text.InlineTextContent>?;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
 final fun com.mikepenz.markdown.model/markdownPadding(androidx.compose.ui.unit/Dp, androidx.compose.ui.unit/Dp, androidx.compose.ui.unit/Dp, androidx.compose.ui.unit/Dp, androidx.compose.ui.unit/Dp?, androidx.compose.ui.unit/Dp, androidx.compose.foundation.layout/PaddingValues?, androidx.compose.foundation.layout/PaddingValues?, androidx.compose.foundation.layout/PaddingValues?, androidx.compose.foundation.layout/PaddingValues.Absolute?, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int): com.mikepenz.markdown.model/MarkdownPadding // com.mikepenz.markdown.model/markdownPadding|markdownPadding(androidx.compose.ui.unit.Dp;androidx.compose.ui.unit.Dp;androidx.compose.ui.unit.Dp;androidx.compose.ui.unit.Dp;androidx.compose.ui.unit.Dp?;androidx.compose.ui.unit.Dp;androidx.compose.foundation.layout.PaddingValues?;androidx.compose.foundation.layout.PaddingValues?;androidx.compose.foundation.layout.PaddingValues?;androidx.compose.foundation.layout.PaddingValues.Absolute?;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
+final fun com.mikepenz.markdown.model/parseMarkdown(kotlin/String, kotlin/Boolean = ..., org.intellij.markdown.flavours/MarkdownFlavourDescriptor = ..., org.intellij.markdown.parser/MarkdownParser = ..., com.mikepenz.markdown.model/ReferenceLinkHandler = ...): com.mikepenz.markdown.model/State // com.mikepenz.markdown.model/parseMarkdown|parseMarkdown(kotlin.String;kotlin.Boolean;org.intellij.markdown.flavours.MarkdownFlavourDescriptor;org.intellij.markdown.parser.MarkdownParser;com.mikepenz.markdown.model.ReferenceLinkHandler){}[0]
 final fun com.mikepenz.markdown.model/parseMarkdownFlow(kotlin/String, kotlin/Boolean = ..., org.intellij.markdown.flavours/MarkdownFlavourDescriptor = ..., org.intellij.markdown.parser/MarkdownParser = ..., com.mikepenz.markdown.model/ReferenceLinkHandler = ...): kotlinx.coroutines.flow/Flow<com.mikepenz.markdown.model/State> // com.mikepenz.markdown.model/parseMarkdownFlow|parseMarkdownFlow(kotlin.String;kotlin.Boolean;org.intellij.markdown.flavours.MarkdownFlavourDescriptor;org.intellij.markdown.parser.MarkdownParser;com.mikepenz.markdown.model.ReferenceLinkHandler){}[0]
 final fun com.mikepenz.markdown.model/rememberMarkdownState(kotlin/Array<out kotlin/Any?>..., kotlin/Boolean, kotlin/Boolean, org.intellij.markdown.flavours/MarkdownFlavourDescriptor?, org.intellij.markdown.parser/MarkdownParser?, com.mikepenz.markdown.model/ReferenceLinkHandler?, kotlin.coroutines/SuspendFunction0<kotlin/String>, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int): com.mikepenz.markdown.model/MarkdownState // com.mikepenz.markdown.model/rememberMarkdownState|rememberMarkdownState(kotlin.Array<out|kotlin.Any?>...;kotlin.Boolean;kotlin.Boolean;org.intellij.markdown.flavours.MarkdownFlavourDescriptor?;org.intellij.markdown.parser.MarkdownParser?;com.mikepenz.markdown.model.ReferenceLinkHandler?;kotlin.coroutines.SuspendFunction0<kotlin.String>;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
 final fun com.mikepenz.markdown.model/rememberMarkdownState(kotlin/String, kotlin/Boolean, kotlin/Boolean, org.intellij.markdown.flavours/MarkdownFlavourDescriptor?, org.intellij.markdown.parser/MarkdownParser?, com.mikepenz.markdown.model/ReferenceLinkHandler?, kotlin/Boolean, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int): com.mikepenz.markdown.model/MarkdownState // com.mikepenz.markdown.model/rememberMarkdownState|rememberMarkdownState(kotlin.String;kotlin.Boolean;kotlin.Boolean;org.intellij.markdown.flavours.MarkdownFlavourDescriptor?;org.intellij.markdown.parser.MarkdownParser?;com.mikepenz.markdown.model.ReferenceLinkHandler?;kotlin.Boolean;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
diff --git a/multiplatform-markdown-renderer/src/commonMain/kotlin/com/mikepenz/markdown/model/MarkdownState.kt b/multiplatform-markdown-renderer/src/commonMain/kotlin/com/mikepenz/markdown/model/MarkdownState.kt
@@ -267,6 +267,42 @@ fun parseMarkdownFlow(
     emitAll(markdownState.state)
 }
 
+/**
+ * Parses the given markdown [content] synchronously and returns the resulting [State] directly.
+ *
+ * Unlike [parseMarkdownFlow], this does not expose any mutable Flow/StateFlow machinery. It performs the
+ * parse on the calling thread and returns the final, immutable [State] (a [State.Success] on success, or a
+ * [State.Error] if the underlying parse fails). This is useful to pre-parse content before the UI is shown
+ * and hand the already-parsed [State.Success] to the `Markdown` composable.
+ *
+ * Note: parsing happens on the calling thread. For large documents consider invoking this off the main thread.
+ *
+ * @param content The markdown content to parse.
+ * @param lookupLinks Whether to lookup links in the parsed tree or not.
+ * @param flavour The [MarkdownFlavourDescriptor] to use for parsing.
+ * @param parser The [MarkdownParser] to use for parsing.
+ * @param referenceLinkHandler The [ReferenceLinkHandler] to use for storing links.
+ *
+ * @return The resulting [State]; [State.Success] on success or [State.Error] on failure.
+ */
+fun parseMarkdown(
+    content: String,
+    lookupLinks: Boolean = true,
+    flavour: MarkdownFlavourDescriptor = GFMFlavourDescriptor(),
+    parser: MarkdownParser = MarkdownParser(flavour),
+    referenceLinkHandler: ReferenceLinkHandler = ReferenceLinkHandlerImpl(),
+): State {
+    return MarkdownStateImpl(
+        Input(
+            content = content,
+            lookupLinks = lookupLinks,
+            flavour = flavour,
+            parser = parser,
+            referenceLinkHandler = referenceLinkHandler,
+        )
+    ).parseBlocking()
+}
+
 /**
  * Transforms a [Flow] of markdown content strings into a [Flow] of parsed [State] for use in non-composable contexts like view models.
  * As soon as the flow is collected, it will start parsing the content, and emit the state once ready.
diff --git a/multiplatform-markdown-renderer/src/commonTest/kotlin/com/mikepenz/markdown/model/ParseMarkdownTest.kt b/multiplatform-markdown-renderer/src/commonTest/kotlin/com/mikepenz/markdown/model/ParseMarkdownTest.kt
@@ -0,0 +1,86 @@
+package com.mikepenz.markdown.model
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertIs
+import kotlin.test.assertTrue
+
+/**
+ * Tests for the synchronous top-level [parseMarkdown] function.
+ */
+class ParseMarkdownTest {
+
+    @Test
+    fun parseMarkdown_happyPath_returnsSuccessSynchronously() {
+        // When parsing a simple heading synchronously (no coroutine/Flow collection)
+        val state = parseMarkdown("# Title")
+
+        // Then the result is a Success carrying the original content and a parsed node
+        val success = assertIs<State.Success>(state)
+        assertEquals("# Title", success.content)
+        assertTrue(success.node.children.isNotEmpty())
+    }
+
+    @Test
+    fun parseMarkdown_emptyContent_returnsSuccess() {
+        // When parsing empty content
+        val state = parseMarkdown("")
+
+        // Then it still resolves to Success (an empty tree), never Loading
+        val success = assertIs<State.Success>(state)
+        assertEquals("", success.content)
+    }
+
+    @Test
+    fun parseMarkdown_withLookupLinks_resolvesReferenceLink() {
+        // Given a document containing a reference link definition
+        val referenceLinkHandler = ReferenceLinkHandlerImpl()
+        val content = """
+            [example]
+
+            [example]: https://example.com
+        """.trimIndent()
+
+        // When parsing with link lookup enabled
+        val state = parseMarkdown(
+            content = content,
+            lookupLinks = true,
+            referenceLinkHandler = referenceLinkHandler,
+        )
+
+        // Then the link is resolved and stored in the provided handler.
+        // The parser keeps the reference label including its surrounding brackets.
+        val success = assertIs<State.Success>(state)
+        assertTrue(success.linksLookedUp)
+        assertEquals("https://example.com", referenceLinkHandler.find("[example]"))
+    }
+
+    @Test
+    fun parseMarkdown_onParseFailure_returnsErrorState() {
+        // Given a reference link handler that throws while storing a resolved link
+        val failure = IllegalStateException("boom")
+        val throwingHandler = object : ReferenceLinkHandler {
+            override fun store(label: String, destination: String?) {
+                throw failure
+            }
+
+            override fun find(label: String): String = ""
+        }
+        val content = """
+            [example]
+
+            [example]: https://example.com
+        """.trimIndent()
+
+        // When parsing with link lookup enabled so the handler is exercised
+        val state = parseMarkdown(
+            content = content,
+            lookupLinks = true,
+            referenceLinkHandler = throwingHandler,
+        )
+
+        // Then the function returns an Error state carrying the throwable, rather than throwing
+        val error = assertIs<State.Error>(state)
+        assertEquals(failure, error.result)
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "Java",`
`3`		`- "image": "mcr.microsoft.com/devcontainers/java:3-21@sha256:1e8bc687983da0d516d1c8d53c15abef59a5c83c0e829331ba145d9910ff4d9c",`
	`3`	`+ "image": "mcr.microsoft.com/devcontainers/java:3-21@sha256:53e4659f8ca8d859366fa0f9bf2d0a56c334a07635e03d26fb6cba2d0885f6c7",`
`4`	`4`	`"features": {`
`5`	`5`	`"ghcr.io/devcontainers/features/java:1": {`
`6`	`6`	`"version": "none",`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ jobs:`
`40`	`40`	`17`
`41`	`41`	`21`
`42`	`42`	`- name: Setup Gradle`
`43`		`- uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0`
	`43`	`+ uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0`
`44`	`44`	`- name: Build Page`
`45`	`45`	`run: \|`
`46`	`46`	`./gradlew sample:web:wasmJsBrowserDistribution --no-configuration-cache`