README.md

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.

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)
}

Embedding instructions refer to these roots with $model/ and $database/. codePath and namedSource(...) are mutually exclusive.

By default, the plugin checks the latest Embed Code release before running a task. It reuses the executable in build/embed-code/latest while the release tag remains unchanged and downloads a new executable only after a new release is published. When the release check fails, for example without network access, the plugin reuses the previously installed executable.

To use a specific Embed Code application release, set version to its exact release tag. The plugin uses this value verbatim and does not add a v prefix.

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

Omit version, or set it to an empty string, to use the latest release. Setting version to "latest" targets a release tag literally named latest; it is not an alias for the latest release.

Before installing an executable, the plugin verifies the release asset's SHA-256 digest from the GitHub Releases API. Only these metadata requests use the optional token; release asset downloads remain unauthenticated. 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, or pin both version and sha256. Pairing the digest with a fixed version keeps the pin valid when GitHub publishes a newer release.

The digest applies to the downloaded release asset. For macOS, this means the ZIP archive rather than the extracted executable. Verified cache metadata is stored under build/embed-code; offline mode reuses the executable only when its current digest, release source, and platform asset still match that metadata.

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.

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.