Skip to content

Add a Kotlin recipe DSL authoring guide - #532

Merged
timtebeek merged 2 commits into
masterfrom
tim/copy-kotlin-recipes-doc
Aug 19, 2026
Merged

Add a Kotlin recipe DSL authoring guide#532
timtebeek merged 2 commits into
masterfrom
tim/copy-kotlin-recipes-doc

Conversation

@timtebeek

Copy link
Copy Markdown
Member

Copies the Writing Kotlin recipes guide from the Moderne docs into the OpenRewrite docs, covering the rewrite { } to { } DSL, imperative kotlin { visit… } scopes, KotlinTemplate, data tables, and how a Kotlin-authored recipe also rewrites Java, Groovy, and Scala.

Adapted rather than copied verbatim: all relative links are remapped to OpenRewrite paths (Moderne-only pages now link out absolutely), and the "running your recipe" section is reframed around the Rewrite Gradle and Maven plugins, since OpenRewrite readers generally won't have the Moderne CLI. The CLI and IntelliJ plugin survive as a single tip about a faster iteration loop and running at scale.

Verified that the page compiles as MDX and that every internal link and anchor resolves; a full yarn build did not run locally due to a disk-space limit, so CI is the real check on broken links.

Adapted from the Moderne docs page of the same name, reframed around the
Rewrite Gradle and Maven plugins, with Moderne CLI and IntelliJ tooling
mentioned only as an optional faster iteration loop.
@timtebeek

Copy link
Copy Markdown
Member Author

How this differs from the Moderne docs page

Source: writing-kotlin-recipes.md. The recipe content — DSL, imperative scopes, KotlinTemplate, data tables, cross-language reach — is carried over unchanged. What differs is everything that assumed a Moderne reader.

Audience: build plugins, not the CLI. OpenRewrite readers generally won't have the Moderne CLI, so the "Running your recipe against a codebase" section was rebuilt around the Rewrite Gradle and Maven plugins:

  • New Running with the Gradle or Maven plugin section: publishToMavenLocal, then a Gradle/Maven <Tabs> block wiring the recipe module into the plugin, ending in rewriteRun / mvn rewrite:run. This section did not exist on the Moderne page.
  • The mod build / mod run --active-recipe / mod config recipes jar install walkthrough is gone. The CLI and IntelliJ plugin survive as a single :::tip — run from compiled classes instead of publishing, attach a debugger, and go wide across many repos — linking out to docs.moderne.io with no commands to copy.
  • Added a pointer to the existing "running Rewrite without modifying the build" guides for Gradle and Maven, which is how you'd realistically try a fresh recipe against a project you don't own.
  • Prerequisites drop "installed and configured the Moderne CLI" in favour of the local recipe development environment guide.
  • Sharing your recipe now ends at publishing to your artifact repository and consuming it via the plugins, plus a pointer to contributing upstream. The Moderne Platform install step is dropped.
  • The $KtRecipe warning is reordered to lead with Gradle build-file escaping (\$KtRecipe), note that Maven XML needs none, and mention shell quoting last — it was command-line-first, which no longer matches where readers hit it.

Docs-site mechanics.

  • Frontmatter uses this repo's sidebar_label + description; the duplicated # title and > blurb from the Moderne export are dropped.
  • Relative links remapped: ../concepts/*../concepts-and-explanations/*, ../references/../reference/, and ../testing-and-best-practices/* / ../advanced-authoring/data-tables.md → siblings in authoring-recipes/. Recipe catalog → /recipes/kotlin. Moderne-only pages (CLI intro, IntelliJ plugin, debugging recipes) are now absolute docs.moderne.io URLs, matching what the JavaScript guides already do.
  • Maven version uses this repo's {{VERSION_REWRITE_MAVEN_PLUGIN}} placeholder, and the tabs use the repo-wide groupId="projectType" so they stay in sync with other pages.
  • The data-tables intro drops "exported as CSV and surfaced on the Moderne Platform" and just links the local data tables guide.
  • Added a cross-link to writing-recipes-over-multiple-source-file-types.md from the JVM-languages section, and to contributing-to-openrewrite.md from the sharing section.

Sidebar entry sits between the JavaScript recipe guide and Refaster.

Anything that drifts on the Moderne side (CLI flags, the 4.4.2 Kotlin-source note) is now only in the tip, so the two pages should need far less coordinated upkeep than a verbatim copy would.

@timtebeek
timtebeek marked this pull request as ready for review August 19, 2026 17:19
@timtebeek
timtebeek merged commit e7dd46c into master Aug 19, 2026
2 checks passed
@timtebeek
timtebeek deleted the tim/copy-kotlin-recipes-doc branch August 19, 2026 17:19
@github-project-automation github-project-automation Bot moved this from In Progress to Done in OpenRewrite Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant