Embed Code Gradle plugin

Gradle plugin for Embed Code, an application that keeps code examples in Markdown and HTML synchronized with their source files.

The plugin downloads the released Embed Code executable for the current platform, so developers and CI jobs do not have to install it manually. It adds two tasks:

• checkEmbedding checks that embedded code is up to date.
• embedCode updates embedded code in place.

Requirements

• Java 17 or a newer version supported by the selected Gradle version.
• Gradle 8.14.4 or newer.
• Linux AMD64, Windows AMD64, or macOS AMD64/ARM64.

Consumers do not need to install Kotlin or apply a Kotlin plugin. The plugin is written in Kotlin, but uses the Kotlin runtime supplied by Gradle.

How to use

This section describes how to use the plugin. For information about the Embed Code application itself, see its documentation.

Configuration

Add the following configuration to the project's build.gradle.kts:

plugins {
    id("io.spine.embed-code") version "0.1.0" // Specify the actual version here.
}

embedCode {

    // Specify the directory containing source files referenced by embedding instructions.
    //
    // This property is required unless `namedSource(...)` is used.
    //
    codePath.set(layout.projectDirectory.dir("src/main/java"))

    // Specify the directory containing Markdown or HTML documentation.
    //
    // This property is required.
    //
    docsPath.set(layout.projectDirectory.dir("docs"))

    // Configure documentation files to include and exclude.
    //
    // This section is optional. The default includes are `**/*.md` and
    // `**/*.html`; the default excludes list is empty.
    //
    docIncludes.set(listOf("**/*.md", "**/*.html"))
    docExcludes.set(listOf("drafts/**", "generated/**"))

    // Configure other Embed Code command-line options.
    //
    // This section is optional. The values below are the defaults.
    //
    separator.set("...")
    info.set(false)
    stacktrace.set(false)
}

Use named source roots when documentation embeds code from multiple modules:

embedCode {
    namedSource(
        "model",
        layout.projectDirectory.dir("model"),
    )
    namedSource(
        "database",
        layout.projectDirectory.dir("database"),
    )
    docsPath.set(layout.projectDirectory)
}

codePath and namedSource(...) are mutually exclusive.

Execution

Check that documentation is up to date:

./gradlew :checkEmbedding

Update documentation:

./gradlew :embedCode

The plugin prefers the checkEmbedding and embedCode task names. If a name is already occupied when the plugin is applied, underscores are prepended until an available name is found, for example _embedCode or __embedCode. The fallback cannot account for a conflicting task registered later.

Version

Each plugin release has a default Embed Code version that was tested with it. The executable is downloaded and verified on its first use. Before reusing it, the plugin compares its digest with the one recorded during installation. This local check does not require a network request. If the executable was modified, the plugin restores it from the authenticated cached release asset, or fails safely when that asset cannot be authenticated offline. Changing version selects a separate cache entry.

To set the application version explicitly, use its exact release tag:

embedCode {
    version.set("v1.2.4")
}

GitHub Authorization

API requests are unauthenticated unless a token provider is configured explicitly:

embedCode {
    githubToken.set(providers.environmentVariable("EMBED_CODE_GITHUB_TOKEN"))
}

For CI, configure githubToken to avoid GitHub's unauthenticated API rate limit during the initial checksum lookup.

Development

Run compilation, plugin validation, and the complete test suite:

./gradlew check

Fast unit tests run under test. TestKit coverage runs separately under functionalTest; the check task includes both.

To test the plugin in another project, publish it to the local Maven repository:

./gradlew :gradle-plugin:publishToMavenLocal

In this case, add mavenLocal() to pluginManagement.repositories in the consuming project's settings.gradle.kts. Adding it only to the regular repositories block does not make Gradle plugin markers available to the plugins block.

License

The plugin is available under the Apache License 2.0.