Docs Examples

Setup Example Sub-module

Add to root build.sbt, for example if the you are creating examples for a webauthn guide:

lazy val `zio-http-example-webauthn` =
  RootProject(file("zio-http-example-webauthn"))

lazy val root = (project in file("."))
  .aggregate(
    // other sub-modules
    `zio-http-example-webauthn`
  )

Inside the example project directory, create a standard Scala project structure, including a build.sbt with necessary dependencies.

Creating Example Files

Step 1: Directory and Package Structure

Create a package directory matching the following pattern:

/src/main/scala//

Where `` is one of:

• -examples (for module references, e.g., http-model-examples)
• -examples (for guides and tutorials, or integration examples spanning multiple modules)

Name conversion rule: Drop hyphens. e.g.:

• query-dsl-sql → querydsl (lowercase, hyphens removed)
• http-model → httpmodel
• scope-resource-management → scoperesourcemanagement

Step 2: Example File Structure

Create one Scala file per major step/concept/use case, plus a final file for the complete example. Each file should be a standalone runnable program, either an object extending App or a Scala 3 @main def function.

Naming convention depends on document type:

| Document Type | File Naming | |---------------|------------| | How-to guides | Step1BasicExample.scala, Step2AdvancedExample.scala, ..., CompleteExample.scala | | Tutorials | Concept1Example.scala, Concept2Example.scala, ..., CompleteExample.scala | | Data type refs | BasicUsage.scala, AdvancedPatterns.scala, CompleteExample.scala (or descriptive names like CompleteHttpRequest.scala) | | Module refs | MultiTypeComposition.scala, CommonPattern1.scala, ..., CompleteExample.scala (titles emphasizing multi-type usage) |

Create 3-5 files total (feel free to write more examples if number of concepts warrants it).

Step 3: Example File Template

Each example file follows this pattern:

For Scala 3:

package 

import 

/**
 *  — Step/Concept/Pattern: 
 *
 * 
 *
 * Run with: sbt "/runMain ."
 */
@main def (): Unit = {
   // Example code
}

For Scala 2.13:

package 

import 

/**
 *  — Step/Concept/Pattern: 
 *
 * 
 *
 * Run with: sbt "/runMain ."
 */
object  extends App {
   // Example code
}

Step 4: The Complete Example

The final example file (CompleteExample.scala or descriptively-named equivalent like CompleteHttpRequest.scala) must contain the entire "Putting It Together" or most complex code block from the document, wrapped in a runnable program (either a Scala 3 @main def function or a Scala 2.13 object extending App). This is the most important example file.

Step 5: Verify Examples Compile

After creating all example files, verify they compile:

sbt "/compile"

Fix any compilation failures before proceeding. The examples must compile successfully.

Step 6: Lint Check (Mandatory Before Integration)

After all examples compile, stage them in git, then run Scalafmt:

git add /src/main/scala/**/*.scala
sbt fmtChanged

If any files were reformatted, commit them immediately:

git add -A
git commit -m "docs(): apply scalafmt to examples"

Verify the CI lint gate locally:

sbt check

Success criterion: Zero formatting violations reported.

---

Step 7: Documenting Examples

When Examples Use SourceFile Embedding

For data type references and module references where examples need detailed documentation:

Place the "Running the Examples" section at the end of the documentation, after all type/module documentation. Use this template:

    ## Running the Examples
    
    All code from this guide is available as runnable examples in the `` module.
    
    **1. Clone the repository and navigate to the project:**
    
    ```bash
    git clone https://github.com/zio/.git
    cd 
    ```
    
    **2. Run individual examples with sbt:**
    
    ### 
    
    
    
    ```scala mdoc:passthrough
    import docs.SourceFile
    
    SourceFile.print("/src/main/scala//.scala")
    ```
    
    ([source](https://github.com/zio//blob/main//src/main/scala//.scala))
    
    ```bash
    sbt "/runMain ."
    ```
    
    ### 
    
    
    
    ```scala mdoc:passthrough
    import docs.SourceFile
    
    SourceFile.print("/src/main/scala//.scala")
    ```
    
    ([source](https://github.com/zio//blob/main//src/main/scala//.scala))
    
    ```bash
    sbt "/runMain ."
    ```

Optional parameters:

• lines = Seq((from, to)) — include only specific line ranges (1-indexed)
• showLineNumbers = true — render with line numbers
• showTitle = false — suppress the file path title

When Examples Use Basic Shell Commands

For how-to guides and tutorials where examples are listed simply:

    ## Running the Examples
    
    All code from this guide/tutorial is available as runnable examples in the `` module.
    
    **1. Clone the repository and navigate to the project:**
    
    ```bash
    git clone https://github.com/zio/.git
    cd 
    ```
    
    **2. Run individual examples with sbt:**
    
    ```bash
    # Step/Concept 1: 
    sbt "/runMain ."
    
    # Step/Concept 2: 
    sbt "/runMain ."
    
    # ...additional steps/concepts...
    
    # Complete example
    sbt "/runMain ."
    ```
    
    **3. Or compile all examples at once:**
    
    ```bash
    sbt "/compile"
    ```

• List every App object in the examples module, one entry per object
• For each entry: use a ### heading (simple, concise title), followed by a short descriptive paragraph
• The paragraph explains what the example demonstrates and the use case/pattern it covers
• For modules: emphasize which types compose in each example
• Embed full source with SourceFile.print (keeps docs and examples in sync automatically)
• Include source link and run command
• Keep the two numbered steps (clone, run individually) in that order

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zio
• Source: zio/zio-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.