ocaml-tutorials

# OCaml Tutorial Creation

## When to Use This Skill

Invoke this skill when:
- Creating tutorials for OCaml libraries
- Working with .mld documentation format
- Setting up MDX for executable examples
- Discussing interactive documentation

## Overview

OCaml tutorials should:
- Introduce concepts gently
- Use executable code examples via MDX
- Progress from simple to complex
- Include practical patterns and use cases

## File Structure

### Required Components

1. **doc/ directory** in project root
2. **tutorial.mld** - Main tutorial content
3. **index.mld** - Documentation index
4. **dune** - Build rules

### doc/dune Configuration

```dune
(mdx
 (files tutorial.mld)
 (libraries your_library_name))

(documentation
 (package your_package_name)
 (mld_files index tutorial))
```

### dune-project Updates

Enable MDX:

```dune
(using mdx 0.4)
```

Add MDX as doc dependency:

```dune
(package
 (name your_package)
 (depends
  ...
  (mdx :with-doc)
  (odoc :with-doc)))
```

## .mld Format

### Document Structure

```
{0 Topic Name Tutorial}

Introduction text.

{1 Section Title}

Section content.

{2 Subsection Title}

Subsection content.
```

### Executable Code Blocks

Use `{@ocaml[...]}` for executable examples:

```
{@ocaml[
# let x = 1 + 1;;
val x : int = 2
]}
```

- Lines starting with `#` are input
- Following lines are expected output
- MDX verifies output at build time
- Use `;;` to terminate expressions

### Non-Executable Code

Use `{v ... v}` for verbatim blocks:

```
{v
name: Alice
age: 30
v}
```

### Cross-References

```
{!Library.function_name}          - Function reference
{!Library.Module.type_name}       - Type reference
{{!Library}API reference}         - Link with custom text
```

### Lists

```
{ul
{- Item one}
{- Item two}
}

{ol
{- First item}
{- Second item}
}
```

### Formatting

```
{b bold text}
{i italic text}
```

## Tutorial Content Guidelines

### Structure

1. **Setup** - How to load the library
2. **Basic Usage** - Simplest examples
3. **