Markout Markdown Plugin (#18)

README.md

@@ -29,7 +29,7 @@ Add the `markout` dependency
 ```kotlin
 /* build.gradle.kts */
 dependencies {
-    implementation("io.koalaql:markout:0.0.6")
+    implementation("io.koalaql:markout:0.0.9")
 }
 ```
 

build-logic/src/main/kotlin/build-config.gradle.kts

@@ -0,0 +1,8 @@
+plugins {
+    id("conventions")
+    id("com.github.gmazzo.buildconfig")
+}
+
+buildConfig {
+    buildConfigField("String", "VERSION", "\"${project.version}\"")
+}

build-logic/src/main/kotlin/publish-plugin.gradle.kts

@@ -1,16 +1,10 @@
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-    id("conventions")
+    id("build-config")
 
     id("java-gradle-plugin")
     id("com.gradle.plugin-publish")
-
-    id("com.github.gmazzo.buildconfig")
-}
-
-buildConfig {
-    buildConfigField("String", "VERSION", "\"${project.version}\"")
 }
 
 java {

build.gradle.kts

@@ -5,6 +5,7 @@ tasks.register("check") {
 tasks.register("publish") {
     dependsOn(listOf(
         gradle.includedBuild("markout-plugin"),
+        gradle.includedBuild("markout-markdown-plugin"),
         gradle.includedBuild("markout-docusaurus-plugin")
     ).map { it.task(":publishPlugins") })
 

docs/MARKDOWN.md

@@ -284,15 +284,15 @@ code("kotlin", """
     }
 """.trimIndent())
 
-val result = code {
-    /* this code block runs */
+val block = code {
+    /* this code block is captured */
     fun square(x: Int) = x*x
 
     square(7)
 }
 
 +"Code executed with result: "
-c("$result")
+c("${block.invoke()}")
 ```
 
 ### Generated
@@ -313,7 +313,7 @@ fun main() {
 ```
 
 ```kotlin
-/* this code block runs */
+/* this code block is captured */
 fun square(x: Int) = x*x
 
 square(7)
@@ -339,7 +339,7 @@ Code executed with result: `49`
 > ```
 > 
 > ```kotlin
-> /* this code block runs */
+> /* this code block is captured */
 > fun square(x: Int) = x*x
 > 
 > square(7)

docusaurus/docs/intro.md

@@ -86,7 +86,7 @@ import TabItem from '@theme/TabItem';
 <TabItem value='main.kt' label='Main.kt'>
 
 ```kotlin
-val markoutVersion = "0.0.7"
+val markoutVersion = "0.0.9"
 
 markout {
     markdown("README.md") {
@@ -112,7 +112,7 @@ markout {
 
 Here's some *generated* Markdown with a list
 
-Using Markout version `0.0.7`
+Using Markout version `0.0.9`
 
 1. One
 2. Two
@@ -125,7 +125,7 @@ Using Markout version `0.0.7`
 > 
 > Here's some *generated* Markdown with a list
 > 
-> Using Markout version `0.0.7`
+> Using Markout version `0.0.9`
 > 
 > 1. One
 > 2. Two
@@ -145,21 +145,15 @@ This allows you to execute your sample code blocks and use the results.
 <TabItem value='main.kt' label='Main.kt'>
 
 ```kotlin
-fun <T> Markdown.execCodeBlock(block: CapturedBlock<T>): T {
-    code("kotlin", block.source.text)
-
-    return block()
-}
-
 markout {
     markdown("EXAMPLE.md") {
-        val result = execCodeBlock {
+        val block = code {
             fun square(x: Int) = x*x
 
             square(7)
         }
 
-        p("The code above results in: $result")
+        p("The code above results in: ${block.invoke()}")
         p("If the result changes unexpectedly then `./gradlew check` will fail")
     }
 }

gradle/libs.versions.toml

@@ -0,0 +1,9 @@
+[versions]
+kapshot = "0.1.1"
+
+[libraries]
+kapshot-runtime = { module = "io.koalaql:kapshot-runtime", version.ref = "kapshot" }
+kapshot-plugin-gradle = { module = "io.koalaql:kapshot-plugin-gradle", version.ref = "kapshot" }
+
+[plugins]
+kapshot = { id = "io.koalaql.kapshot-plugin", version.ref = "kapshot" }

markout-docusaurus-plugin/build.gradle.kts

@@ -4,8 +4,7 @@ plugins {
 
 dependencies {
     implementation("com.github.node-gradle:gradle-node-plugin:3.5.1")
-    implementation("io.koalaql:kapshot-plugin-gradle:0.1.1")
-    implementation("io.koalaql:markout-plugin:${project.version}")
+    implementation("io.koalaql:markout-markdown-plugin:${project.version}")
 }
 
 pluginBundle {

markout-docusaurus-plugin/src/main/kotlin/io/koalaql/markout/docusaurus/GradlePlugin.kt

@@ -9,10 +9,9 @@ import com.github.gradle.node.yarn.exec.YarnExecRunner
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import com.github.gradle.node.yarn.task.YarnTask
-import io.koalaql.markout_plugin.BuildConfig
+import io.koalaql.markout_docusaurus_plugin.BuildConfig
 import org.gradle.api.Action
 import org.gradle.api.DefaultTask
-import org.gradle.api.file.Directory
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.provider.ProviderFactory
 import org.gradle.api.tasks.Input
@@ -25,13 +24,10 @@ import org.gradle.deployment.internal.DeploymentRegistry
 import org.gradle.nativeplatform.platform.internal.DefaultNativePlatform
 import org.gradle.process.ExecResult
 import org.gradle.process.ExecSpec
-import java.io.File
-import java.nio.file.Path
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicReference
 import javax.inject.Inject
 import kotlin.concurrent.thread
-import org.gradle.api.provider.Provider
 import kotlin.io.readLines
 
 class StopHandle {

markout-markdown-plugin/build.gradle.kts

@@ -0,0 +1,25 @@
+plugins {
+    id("publish-plugin")
+}
+
+dependencies {
+    implementation(libs.kapshot.plugin.gradle)
+    implementation("io.koalaql:markout-plugin:${project.version}")
+}
+
+pluginBundle {
+    website = "https://github.com/mfwgenerics/markout"
+    vcsUrl = "https://github.com/mfwgenerics/markout.git"
+    tags = listOf("kotlin", "markout", "markdown", "jvm", "documentation")
+}
+
+gradlePlugin {
+    plugins {
+        create("markoutPlugin") {
+            id = "io.koalaql.markout-markdown"
+            displayName = "Markout Markdown Plugin"
+            description = "Plugin Support for Markout Markdown Generation and Code Capture"
+            implementationClass = "io.koalaql.markout.markdown.GradlePlugin"
+        }
+    }
+}

markout-markdown-plugin/settings.gradle.kts

@@ -0,0 +1,7 @@
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}

markout-markdown-plugin/src/main/kotlin/GradlePlugin.kt

@@ -0,0 +1,19 @@
+package io.koalaql.markout.markdown
+
+import io.koalaql.markout_markdown_plugin.BuildConfig
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+class GradlePlugin: Plugin<Project> {
+    override fun apply(target: Project) = with(target) {
+        dependencies.add("api", "io.koalaql:markout-markdown:${BuildConfig.VERSION}")
+        dependencies.add("api", "io.koalaql:markout-docusaurus:${BuildConfig.VERSION}")
+
+        with(plugins) {
+            apply("io.koalaql.markout")
+            apply("io.koalaql.kapshot-plugin")
+        }
+
+        Unit
+    }
+}

markout-markdown/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
 
 dependencies {
     api(kotlin("reflect"))
+    api(libs.kapshot.runtime)
 
     api("io.koalaql:markout")
 

markout-markdown/settings.gradle.kts

@@ -0,0 +1,7 @@
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}

markout-markdown/src/main/kotlin/io/koalaql/markout/md/Markdown.kt

@@ -1,5 +1,7 @@
 package io.koalaql.markout.md
 
+import io.koalaql.kapshot.Capturable
+import io.koalaql.kapshot.CapturedBlock
 import io.koalaql.markout.MarkoutDsl
 
 @MarkoutDsl
@@ -54,6 +56,10 @@ interface Markdown: MarkdownBlock {
     @MarkoutDsl
     fun code(code: String) = code("", code)
 
+    @MarkoutDsl
+    fun <T> code(block: CapturedBlock<T>): CapturedBlock<T> =
+        block.also { code("kotlin", it.source.text) }
+
     @MarkoutDsl
     fun ol(builder: MarkdownNumberedList.() -> Unit)
     @MarkoutDsl

readme/src/main/kotlin/Constants.kt

@@ -1 +1 @@
-const val MARKOUT_VERSION: String = "0.0.7"
+const val MARKOUT_VERSION: String = "0.0.9"

readme/src/main/kotlin/FileGen.kt

@@ -47,7 +47,7 @@ fun Markout.fileGen() = markdown("FILES") {
 
             -"When this code is run it generates the following file tree"
 
-            code(drawFileTree(output))
+            code(drawFileTree(output.invoke()))
 
             h3("File Tracking")
 

readme/src/main/kotlin/Main.kt

@@ -6,8 +6,6 @@ import workflows.deployGhPagesYml
 import workflows.releaseYml
 import kotlin.io.path.Path
 
-private val CURRENT_VERSION = "0.0.6"
-
 fun main() = markout {
     directory(".github") {
         directory("workflows") {
@@ -60,7 +58,7 @@ fun main() = markout {
                     """
                     /* build.gradle.kts */
                     dependencies {
-                        implementation("io.koalaql:markout:$CURRENT_VERSION")
+                        implementation("io.koalaql:markout:$MARKOUT_VERSION")
                     }
                     """.trimIndent()
                 )
@@ -103,7 +101,7 @@ fun main() = markout {
 
                 -"The above will produce the String"
 
-                code("markdown", result)
+                code("markdown", result.invoke())
             }
 
             section("Usage") {

readme/src/main/kotlin/Markdown.kt

@@ -11,9 +11,6 @@ fun <T> Markdown.code(lang: String, code: CapturedBlock<T>): T {
     return code()
 }
 
-@MarkoutDsl
-fun <T> Markdown.code(code: CapturedBlock<T>): T = code("kotlin", code)
-
 fun Markout.markdownDocs() = markdown("MARKDOWN") {
     h1("Markdown")
 
@@ -137,15 +134,15 @@ fun Markout.markdownDocs() = markdown("MARKDOWN") {
                     }
                 """.trimIndent())
 
-                val result = code {
-                    /* this code block runs */
+                val block = code {
+                    /* this code block is captured */
                     fun square(x: Int) = x*x
 
                     square(7)
                 }
 
                 +"Code executed with result: "
-                c("$result")
+                c("${block.invoke()}")
             }
         }
 

readme/src/main/kotlin/docusaurus/Intro.kt

@@ -88,21 +88,15 @@ private fun DocusaurusMarkdown.sourceCaptureExample() {
     }
 
     val source = execBlock {
-        fun <T> Markdown.execCodeBlock(block: CapturedBlock<T>): T {
-            code("kotlin", block.source.text)
-
-            return block()
-        }
-
         markout {
             markdown("EXAMPLE.md") {
-                val result = execCodeBlock {
+                val block = code {
                     fun square(x: Int) = x*x
 
                     square(7)
                 }
 
-                p("The code above results in: $result")
+                p("The code above results in: ${block.invoke()}")
                 p("If the result changes unexpectedly then `./gradlew check` will fail")
             }
         }

settings.gradle.kts

@@ -1,8 +1,12 @@
 includeBuild("build-logic")
-includeBuild("markout-plugin")
-includeBuild("markout-docusaurus-plugin")
 includeBuild("markout")
+includeBuild("markout-plugin")
 includeBuild("markout-markdown")
+includeBuild("markout-markdown-plugin")
 includeBuild("markout-docusaurus")
+includeBuild("markout-docusaurus-plugin")
 includeBuild("markout-github-workflows-kt")
+
+includeBuild("testing")
+
 include("readme")

testing/build.gradle.kts

@@ -0,0 +1,3 @@
+tasks.register("check") {
+    dependsOn(":markdown-plugin:check")
+}