Add Grails 8 JobRunr guide

[jamesfredley]

Summary

• add a production-oriented Grails 8 guide for durable JobRunr OSS background jobs
• publish branch-aware sample downloads and complete, synchronized application snippets
• improve shared guide accessibility, responsive navigation, code containment, and print behavior

Verification

• validateGuides -PvalidationMode=both: 98 guides, 0 errors
• verifyAllGuides: 3,723 rendered HTML files, JobRunr crawl VERIFIED with 0 broken references
• public sample test integrationTest passed on Java 21
• browser matrix: all 10 chapters at 375px, 768px, and 1280px with no document overflow, broken images, or duplicate IDs
• keyboard TOC, clipboard copy, print wrapping, and legacy iframe sizing verified in Chromium
• two independent visual QA passes inspected all 31 fresh captures and passed

Sample

• https://github.com/grails-guides/grails-jobrunr/tree/grails8
• https://github.com/grails-guides/grails-jobrunr/archive/grails8.zip

[Copilot]

Pull request overview

Adds a new production-oriented Grails 8 guide for durable background jobs using JobRunr OSS, including a complete/sample application with synchronized snippets and improved shared guide UX (accessibility, responsive layout, and branch-aware downloads).

Changes:

• Publish the new grails-jobrunr Grails 8 guide with full chapter content and metadata wiring in conf/guides.yml.
• Add “initial” and “complete” Gradle-based sample application snippets (code + tests) for the guide.
• Improve guide templates/CSS for accessibility (focus-visible styling, ARIA labels), responsive navigation/containment, and branch-aware ZIP downloads.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
guides/resources/style/layout.html	Adds ARIA labels to “Get the Code” controls and makes ZIP downloads branch-aware.
guides/resources/style/guideItem.html	Improves standalone chapter pages with viewport meta, keyboard-friendly TOC behavior, clipboard support, and branch-aware ZIP link.
guides/resources/css/guide.css	Adds focus-visible styling, responsive chapter layout improvements, dropdown TOC behavior, and print/code containment adjustments.
guides/grails-jobrunr/v8/snippets/initial/gradle.properties	Introduces Gradle properties for the “initial” sample app.
guides/grails-jobrunr/v8/snippets/initial/build.gradle	Adds the baseline Grails 8 build for the “initial” sample app.
guides/grails-jobrunr/v8/snippets/complete/src/test/groovy/example/grails/JobRunrIntegrationSpec.groovy	Adds an integration test covering JobRunr execution + dedicated datasource separation.
guides/grails-jobrunr/v8/snippets/complete/src/test/groovy/example/grails/jobrunr/JobRunrStorageConfigSpec.groovy	Adds a unit test validating storage provider table prefix + skip-create behavior.
guides/grails-jobrunr/v8/snippets/complete/src/test/groovy/example/grails/jobrunr/JobRequestSpec.groovy	Adds a unit test for JobRequest deserialization + handler mapping.
guides/grails-jobrunr/v8/snippets/complete/src/test/groovy/example/grails/DeliveryJobEnqueuerSpec.groovy	Adds a unit test for after-commit enqueue semantics and request scheduling.
guides/grails-jobrunr/v8/snippets/complete/src/test/groovy/example/grails/DeliveryHttpApiSpec.groovy	Adds HTTP integration tests for delivery creation routing and validation response behavior.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/jobrunr/RetryDeliveryJobRequestHandler.groovy	Adds a retry demo JobRequestHandler that intentionally fails to show retry behavior.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/jobrunr/RetryDeliveryJobRequest.groovy	Adds a retry demo JobRequest type mapping to its handler.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/jobrunr/ProcessDeliveryJobRequest.groovy	Adds the primary JobRequest type used for durable processing.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/jobrunr/JobRunrStorageConfig.groovy	Adds explicit StorageProvider wiring for the dedicated JobRunr datasource.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/jobrunr/DeliveryJobRequestHandler.groovy	Adds the transactional job handler that updates delivery state/progress and preserves interrupts.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/DeliveryJobEnqueuer.groovy	Adds a transactional event listener that enqueues after commit.
guides/grails-jobrunr/v8/snippets/complete/src/main/groovy/example/grails/DeliveryCreatedEvent.groovy	Adds a lightweight domain event carrying only the delivery ID.
guides/grails-jobrunr/v8/snippets/complete/grails-app/services/example/grails/JobExamplesService.groovy	Adds service methods demonstrating immediate/delayed/recurring/retry JobRunr APIs.
guides/grails-jobrunr/v8/snippets/complete/grails-app/services/example/grails/DeliveryService.groovy	Adds a transactional delivery creation service that publishes the event.
guides/grails-jobrunr/v8/snippets/complete/grails-app/init/example/grails/Application.groovy	Adds Grails app bootstrap importing storage config and scanning components.
guides/grails-jobrunr/v8/snippets/complete/grails-app/domain/example/grails/Delivery.groovy	Adds the Delivery domain model used in the sample/guide.
guides/grails-jobrunr/v8/snippets/complete/grails-app/controllers/example/grails/UrlMappings.groovy	Adds URL mappings for delivery and job example endpoints.
guides/grails-jobrunr/v8/snippets/complete/grails-app/controllers/example/grails/JobExamplesController.groovy	Adds JSON endpoints returning job IDs for async operations.
guides/grails-jobrunr/v8/snippets/complete/grails-app/controllers/example/grails/DeliveryController.groovy	Adds delivery create/show JSON endpoints with 201/404/422 behavior.
guides/grails-jobrunr/v8/snippets/complete/grails-app/conf/spring/resources.groovy	Registers TransactionalEventListenerFactory so after-commit listeners work.
guides/grails-jobrunr/v8/snippets/complete/grails-app/conf/application.yml	Adds application + JobRunr configuration including separate datasource and environment overrides.
guides/grails-jobrunr/v8/snippets/complete/gradle.properties	Defines Grails/JobRunr versions and Gradle performance properties for the complete sample.
guides/grails-jobrunr/v8/snippets/complete/build.gradle	Adds JobRunr starter + Jackson Databind dependency and a dev bootRun configuration.
guides/grails-jobrunr/v8/guide/testing.adoc	Documents the sample’s unit/integration testing strategy with snippet includes.
guides/grails-jobrunr/v8/guide/storageConfiguration.adoc	Documents dedicated JobRunr storage wiring and production schema ownership guidance.
guides/grails-jobrunr/v8/guide/runningTheApp.adoc	Documents running the sample, exercising endpoints, and using the dashboard.
guides/grails-jobrunr/v8/guide/requirements.adoc	Lists requirements (Java 21, Gradle wrapper) and constraints for learning vs production.
guides/grails-jobrunr/v8/guide/operations.adoc	Adds production operations guidance (storage, dashboard, idempotency, metrics, OSS/Pro boundary).
guides/grails-jobrunr/v8/guide/jobRequests.adoc	Explains why not to enqueue Groovy closures and how to use JobRequest/Handler properly.
guides/grails-jobrunr/v8/guide/jobApis.adoc	Documents immediate/delayed/recurring/retry APIs and ties them to sample endpoints.
guides/grails-jobrunr/v8/guide/howto.adoc	Provides “how to complete the guide” instructions and repo clone steps.
guides/grails-jobrunr/v8/guide/helpWithGrails.adoc	Includes shared “help with Grails” content.
guides/grails-jobrunr/v8/guide/gettingStarted.adoc	Introduces JobRunr in Grails 8, versions used, and what the reader will build.
guides/grails-jobrunr/v8/guide/durableEnqueue.adoc	Documents after-commit enqueue pattern and OSS limitations/outbox guidance.
guides/grails-jobrunr/v8/guide/dependencySetup.adoc	Documents adding JobRunr + Jackson and contrasts initial vs complete builds.
conf/guides.yml	Registers the new guide (metadata, tags, toc, sample repo/branch).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bito-code-review]

The concern regarding layout shifts caused by margin-left: 4px on focused TOC links is valid. Using properties that affect layout, such as margins or padding, can indeed cause UI jank and shift surrounding elements when focus is applied or removed.

To avoid this, consider using non-layout-shifting alternatives for focus styling, such as:

• Outline: Use the outline property, which is drawn outside the element's box model and does not affect layout.
• Box Shadow: Use box-shadow to create a focus ring, which also does not impact the layout of the element or its neighbors.
• Background/Color Changes: Modify the background-color or color of the link, which provides visual feedback without changing the element's dimensions.

Since the file guides/resources/css/guide.css was not found in the provided PR context, please verify the file path or check if the CSS is defined in a different location within the repository.

[jamesfredley]

@sanjana2505006 Please review this guide for me. The companion app: https://github.com/grails-guides/grails-jobrunr

[sanjana2505006]

@jamesfredley Thank you for asking me to review this, I've learned a lot from your feedback on my guides, so I tried to be as careful here.

Overall this looks solid. The sample design is clear (JobRequest over Groovy closures, AFTER_COMMIT enqueue, dedicated dataSource_jobrunr, OSS vs Pro called out), and the vendored snippets match grails-guides/grails-jobrunr@grails8 for the files I diffed. Branch-aware ZIP download is a nice fix too.

A few notes:

1. TOC label vs content — under gettingStarted, requirements is titled "What You Will Build and Need", but requirements.adoc is only prerequisites. "What you will build" lives in gettingStarted.adoc. Other guides use "What you will need" here; maybe align?

2. Shared guide chrome — guide.css / guideItem.html / layout.html change all guides (viewport, TOC focus, chapter nav, print wrapping, #main h1/h2 → #d97706). The a11y/responsive bits look good; just confirming the amber headings are intentional site-wide.

3. Snippet coverage, companion has JobExamplesControllerSpec / JobExamplesServiceSpec that aren't vendored. Fine if intentional (guide doesn't include them); mentioning in case you want parity.

4. Small runbook nits (optional):

   • runningTheApp curl examples could add -H "Content-Type: application/x-www-form-urlencoded" for the POST (works without it, but clearer for copy-paste).
   • xrefs to operations.adoc#operations — please confirm #operations resolves in the rendered HTML (no explicit [[operations]] in the adoc).

Companion looks good: grails-jobrunr