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

Prose in .mld pages and in the doc comments a tutorial quotes follows the doc-style skill. Load it before writing them. A tutorial may address the reader and explain motivation, which reference documentation may not, but the sentences are still complete and free of filler.

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

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

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

dune-project Updates

Enable MDX:

(using mdx 0.4)

Add MDX as doc dependency:

(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