docs: reference the Mutiny workshop examples

README.md

@@ -49,6 +49,12 @@ Mutiny is based on the [Reactive Streams protocol](https://www.reactive-streams.
 
 In addition, Mutiny offers converters to interact with other popular libraries and [Kotlin](https://kotlinlang.org/).
 
+## 👓 Mutiny workshop examples
+
+You can learn about Mutiny from the [documentation and website](https://smallrye.io/smallrye-mutiny).
+
+This repository also contains the [Mutiny workshop examples](workshop-examples) that cover the common concerns through self-contained executable [JBang](https://www.jbang.dev/) scripts.
+
 ## 📦 Build instructions
 
 Mutiny is built with Apache Maven, so all you need is:

documentation/docs/tutorials/mutiny-workshop.md

@@ -0,0 +1,17 @@
+---
+tags:
+- tutorial
+- beginner
+---
+
+# Go further with the Mutiny workshop!
+
+One great option to teach yourself Mutiny is to go through the [Mutiny workshop examples](https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples).
+
+These self-contained [JBang](https://jbang.dev/) scripts cover the main parts of the Mutiny APIs.
+
+It's a fun and easy way to discover Mutiny!
+
+Check out [https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples](https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples) to learn more.
+
+![Running a workshop sample](running-workshop-sample.png){ width="400" }

documentation/mkdocs.yml

@@ -15,6 +15,7 @@ nav:
       - 'tutorials/transforming-items-asynchronously.md'
       - 'tutorials/handling-failures.md'
       - 'tutorials/retrying.md'
+      - 'tutorials/mutiny-workshop.md'
   - 'Guides':
       - 'guides/imperative-to-reactive.md'
       - 'guides/reactive-to-imperative.md'

workshop-examples/README.md

@@ -0,0 +1,29 @@
+# Mutiny workshop examples
+
+This project contains learning examples for Mutiny, covering a wide range of topics such as the basics, transformations, error recovery and more.
+
+## Structure
+
+The examples are found in `src/main/java` and use a non-conventional file naming strategy.
+
+For instance you will find the failure handling examples in `_04_failures` where `_04_Uni_Failure_Retry.java` holds one such example.
+
+This naming scheme is not usual for Java programs, but it makes for a great way to organize files 😄
+
+## Running the examples
+
+Each file is a self-contained class with a `main` method.
+
+A friendly option is to open the Maven project in your favorite IDE, then run the `main` method of each example of interest.
+
+The other option is to use [JBang](https://www.jbang.dev/) as each example is a valid JBang script:
+
+```shell
+jbang src/main/java/_05_backpressure/_03_Visual_Drop.java
+```
+
+What's more each file is Unix-executable, so you can also run as:
+
+```shell
+./src/main/java/_05_backpressure/_03_Visual_Drop.java
+```