Error when running 'knit' task - "TEST must be preceded by knitted file"

[aSemy]

I've been trying to set up Knit, based on the README and what I can see in Kotlinx Serialization. However I get an error.

ERROR: project\docs\basic-classes.md: 40: TEST must be preceded by knitted file

I'd like to know what the minimal example is. I found the README quite dense and difficult to read - I'd really like a small example, just to get started.

I'm using version 0.3.0, but I don't see that documented. Is this the correct version to use?

---

I have a multi-project Gradle project. There's :modules:core (which I want to document), :modules:knit where I've applied the knit plugin, and the ./docs directory with a markdown file basic-classes.md and a knit.properties

knit.dir=../modules/my-project-knit/example/
test.dir=../modules/my-project-knit/test/
knit.package=example
test.package=example.test

I also created a basic-classes.md file, with what I think is a minimal example.

<!--- TEST_NAME BasicClassesTest -->

**Table of contents**

<!--- TOC -->

* [Introduction](#introduction)
  * [Plain classes with primitive fields](#plain-class-with-primitive-fields)

<!--- END -->

## Introduction

Lorem ipsum...

### Plain class with primitive fields

<!--- INCLUDE
import kotlinx.serialization.*
import kotlinx.serialization.json.*
-->

```kotlin
@Serializable
class Color(val rgb: Int)

fun main() {
    val green = Color(0x00ff00)
    println(Json.encodeToString(green))
}
```

> You can get the full code [here](../modules/my-project-knit/example/plain-class-with-primitive-fields-01.kt).

```text
{"rgb":65280}
```

<!--- TEST -->

In ./modules/my-project-knit/build.gradle.kts I apply the knit plugin, as well as the Kotlin JVM plugin.

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
  kotlin("jvm")
  kotlin("plugin.serialization")
  id("org.jetbrains.kotlinx.knit")
}

val kotlinxSerializationVersion = "1.3.2"

dependencies {
  implementation(projects.modules.core)

  implementation(platform("org.jetbrains.kotlinx:kotlinx-serialization-bom:${kotlinxSerializationVersion}"))
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json")
}

tasks.withType<KotlinCompile> {
  kotlinOptions.freeCompilerArgs += listOf(
    "-opt-in=kotlinx.serialization.ExperimentalSerializationApi",
  )
}

sourceSets.test {
  java.srcDirs("test", "example")
}

But when I run the 'knit' task, I get an error

> Task :modulesmy-project-knitt:knitPrepare UP-TO-DATE
Skipping task ':modules:my-project-knit:knitPrepare' as it has no actions.
:modules:my-project-knit:knitPrepare (Thread[Execution worker for ':',5,main]) completed. Took 0.001 secs.
:modules:my-project-knit:knit (Thread[Execution worker for ':',5,main]) started.

> Task :modules:my-project-knit:knit FAILED
Caching disabled for task ':modules:my-project-knit:knit' because:
  Build cache is disabled
Task ':modules:my-project-knit:knit' is not up-to-date because:
  Task has not declared any outputs despite executing actions.
*** Reading project\build.gradle.kts
*** Reading project\buildSrc\build.gradle.kts
*** Reading project\buildSrc\repositories.settings.gradle.kts
*** Reading project\buildSrc\settings.gradle.kts
*** Reading project\buildSrc\src\main\kotlin\project\config\gradle.kt
*** Reading project\buildSrc\src\main\kotlin\project\convention\jacoco-aggregation.gradle.kts
*** Reading project\buildSrc\src\main\kotlin\project\convention\kotlin-jvm.gradle.kts
*** Reading project\buildSrc\src\main\kotlin\project\convention\subproject.gradle.kts
*** Reading project\docs\basic-classes.md
:modules:my-project-knit:knit (Thread[Execution worker for ':',5,main]) completed. Took 0.033 secs.
13 actionable tasks: 1 executed, 12 up-to-date
Watched directory hierarchies: [project]
ERROR: project\docs\basic-classes.md: 40: TEST must be preceded by knitted file

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':modules:my-project-knit:knit'.
> knit task failed, see log for details (use '--info' for detailed log).

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --debug option to get more log output.
> Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 568ms
Execution finished 'knit --info'.

[aSemy]

Okay I figured it out!

The filename should be prefixed with example-

wrong:

> You can get the full code [here](../modules/my-project-knit/example/plain-class-with-primitive-fields-01.kt).

right:

> You can get the full code [here](../modules/ts-generator-knit/example/example-plain-class-primitive-fields-01.kt).

This is documented in the README, but it's buried in the middle of a section so it's not easy to see.

The name of the example file must match a specific pattern. By default, this pattern's regex is example-[a-zA-Z0-9-]+-##\\.kt. It can be overridden via knit.pattern property.

1. Why is this specific pattern required? Because the file is generated into a specific knit.dir, can't example files be any pattern by default?
2. Can we get a more clear error message for the cause of TEST must be preceded by knitted file? Or a error-level log message? Something like ERROR: knitted file ${filename} does not match pattern ${knit.pattern}
3. It would be helpful to have a full list of the properties that are valid in a knit.properties file, with the default and a link to the documentation.

property	default	required	summary
knit.dir	example-prefix-comment	yes	the location of XYZ <click for docs>
knit.pattern	example-[a-zA-Z0-9-]+-##\\.kt	no	example files must match this pattern <click for docs>