Add Markdown backend for Asciidoctor docs

[leonard84]

Motivation

In the age of agentic AI, it is important that documentation be AI-accessible.
HTML is token-intensive, and stripping it down could cause conversion errors.
So this PR adds the capability to publish markdown alongside the HTML docs to make the documentation better accessible to AI Agents

Summary

• Adds a custom MarkdownConverter that renders the Spock docs as GitHub-flavored Markdown alongside the existing HTML output.
• Wires a separate Asciidoctor Gradle task for the markdown backend so diagram generation is skipped, and includes the markdown output in publishDocs.
• Fixes several conversion issues discovered along the way: HTML entity decoding, double-nested links, output paths, lost emphasis in list items, inline_break handling (preserving leading text and + continuations), and skipping IncludedSourceLinker table wrapping for the markdown backend.
• DRYs the converter with shared helpers after the initial node-type implementations landed.

Summary by CodeRabbit

Release Notes

• New Features

  • Added Markdown export support for project documentation, enabling generation of documentation in Markdown format alongside HTML.

• Chores

  • Updated documentation build workflows to generate Markdown output as part of the standard build process.
  • Refactored internal documentation build configuration for better maintainability.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: acb14dd4-4816-460a-bf24-4445bd4e4214

📥 Commits

Reviewing files that changed from the base of the PR and between a6037c2 and 4058ea7.

📒 Files selected for processing (7)

• .github/workflows/docs-pr.main.kts
• .github/workflows/docs-pr.yaml
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/IncludedSourceLinker.java
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverter.java
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverterRegistry.java
• build-logic/asciidoc-extensions/src/main/resources/META-INF/services/org.asciidoctor.jruby.converter.spi.ConverterRegistry
• build.gradle

👮 Files not reviewed due to content moderation or server errors (7)

• .github/workflows/docs-pr.yaml
• .github/workflows/docs-pr.main.kts
• build-logic/asciidoc-extensions/src/main/resources/META-INF/services/org.asciidoctor.jruby.converter.spi.ConverterRegistry
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/IncludedSourceLinker.java
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverterRegistry.java
• build.gradle
• build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverter.java

---

📝 Walkthrough

Walkthrough

This PR introduces Markdown documentation output support to the build system. A new Asciidoctor converter transforms AsciiDoc to Markdown format, registered via SPI. Gradle tasks and CI workflows are updated to generate Markdown alongside HTML documentation. Source linking logic conditionally skips table wrapping for Markdown output.

Changes

Cohort / File(s)	Summary
Workflow Updates .github/workflows/docs-pr.main.kts, .github/workflows/docs-pr.yaml	Both workflows extended to invoke asciidoctorMarkdown Gradle task alongside existing asciidoctor and javadoc tasks in the "Docs and JavaDoc" build step.
Markdown Converter Implementation build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverter.java	New StringConverter implementation (439 lines) that converts AsciiDoc nodes to Markdown format, handling documents, sections, lists, tables, admonitions, images, inline elements, with entity decoding and special GitHub-flavored Markdown support.
Converter Registration build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/MarkdownConverterRegistry.java, build-logic/asciidoc-extensions/src/main/resources/META-INF/services/org.asciidoctor.jruby.converter.spi.ConverterRegistry	New ConverterRegistry implementation registering the MarkdownConverter with Asciidoctor at runtime; SPI entry enables automatic service discovery.
Source Linker Conditional Logic build-logic/asciidoc-extensions/src/main/java/org/spockframework/plugins/asciidoctor/IncludedSourceLinker.java	Early return added in processBlocks when backend attribute equals "markdown" to prevent AsciiDoc table-wrapping logic for Markdown output.
Gradle Build Configuration build.gradle	New asciidoctorMarkdown task registered to generate Markdown output; shared configureAsciidoctor closure introduced to centralize configuration for both asciidoctor and asciidoctorMarkdown tasks; diagram.use() module moved from top-level to asciidoctor task; publishDocs task extended to publish both HTML and Markdown artifacts.

Sequence Diagram(s)

sequenceDiagram
    participant Workflow as CI Workflow
    participant Gradle as Gradle Build
    participant Registry as Service Loader
    participant Converter as MarkdownConverter
    participant Asciidoctor as Asciidoctor Engine

    Workflow->>Gradle: Execute asciidoctorMarkdown task
    Gradle->>Registry: Initialize ConverterRegistry (SPI)
    Registry->>Registry: Discover MarkdownConverterRegistry
    Registry->>Converter: Register MarkdownConverter instance
    Gradle->>Asciidoctor: Process AsciiDoc with backend=markdown
    Asciidoctor->>Converter: convert(node, transform, opts)
    Converter->>Converter: Dispatch by node type (doc, section, table, etc.)
    Converter->>Converter: Entity decode & format as Markdown
    Converter-->>Asciidoctor: Return Markdown string
    Asciidoctor-->>Gradle: Generated Markdown docs
    Gradle->>Gradle: Output to build/docs/asciidocMarkdown/

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐰 A markdown garden springs to life,
Where AsciiDoc transforms, free from strife—
Tables skip their dance, backends aligned,
Converters register, perfectly designed.
From workflow to gradle, the documents flow,
HTML and Markdown—both steal the show! 📝✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Markdown backend for Asciidoctor docs' directly and accurately describes the main change: adding a new Markdown backend for Asciidoctor documentation generation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: 4058ea7
▶️ Tests: 88189 executed
⚪️ Checks: 33/33 completed

---

Learn more about TestLens at testlens.app.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.16%. Comparing base (a6037c2) to head (4058ea7).

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #2340      +/-   ##
============================================
- Coverage     82.17%   82.16%   -0.02%     
+ Complexity     4826     4824       -2     
============================================
  Files           472      472              
  Lines         15040    15040              
  Branches       1908     1908              
============================================
- Hits          12359    12357       -2     
- Misses         1990     1991       +1     
- Partials        691      692       +1     

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.