Skip to content
Skills Library
Programming · Writing

tutorials

/tutorials

Creating OCaml library tutorials using .mld documentation format with MDX executable examples. Use when discussing tutorials, documentation, .mld files, MDX, or interactive documentation.

Author
avsm ↗
Licence
ISC
Last repository change
02.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.

Licence

ISC, otwarta.

What it does and when to use it

Creating OCaml library tutorials using .mld documentation format with MDX executable examples. Use when discussing tutorials, documentation, .mld files, MDX, or interactive documentation.

Original author description

Creating OCaml library tutorials using .mld documentation format with MDX executable examples. Use when discussing tutorials, documentation, .mld files, MDX, or interactive documentation.

How it works

  1. When to Use This Skill
  2. Overview
  3. File Structure
  4. .mld Format
  5. Tutorial Content Guidelines
  6. Verification
  7. Common Issues
Original SKILL.md headings · 188 lines, 504 words
SKILL.md preview
---
name: tutorials
description: Creating OCaml library tutorials using .mld documentation format with MDX executable examples. Use when discussing tutorials, documentation, .mld files, MDX, or interactive documentation.
---

# 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

```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. **Core Concepts** - Main types and functions
4. **Common Patterns** - Real-world usage
5. **Advanced Features** - Complex functionality
6. **Error Handling** - How errors work
7. **Summary** - Quick reference

### Setup Section

```
{1 Setup}

{@ocaml[
# #require "library_name";;
# open Library;;
]}
```

### Best Practices

1. **Show output** - Include expected output in examples
2. **Use consistent naming** - Variables carry through examples
3. **Build complexity gradually** - Each example builds on previous
4. **Explain the "why"** - Not just syntax, but when to use features
5. **Reference documentation** - Link to API docs

## Verification

```bash
dune build @check    # Verify syntax
dune build @doc      # Build documentation
dune runtest         # Run MDX tests (if configured)
```

## Common Issues

### Unresolved References
Use fully qualified names: `{!Library.of_string}` not `{!of_string}`

### MDX Not Found
Enable in dune-project: `(using mdx 0.4)`

### Output Mismatch
Run code manually, update expected output. Use `<abstr>` for abstract values.

Versions

The database has no other skills named tutorials.

Database snapshot: 13.11.2026 · package version d1a48a177c05 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100doc-style
    OCaml comment and ocamldoc writing style, in the voice of a POSIX manual page. Use whenever writing, rewording, reviewing or deleting any OCaml comment or documentation. Triggers on ocamldoc, odoc, doc comments, (** ... *), .mli documentation, .mld pages, documenting a function,…
  • 100writing-tutorials
    Creates Medusa documentation tutorials in two phases: first builds the tutorial feature in an example project (with planning, coding, and tests), then writes the MDX documentation. Use when creating a new how-to tutorial or integration guide for the Medusa docs. Handles both…
  • 100react-component-documentation
    Create or update component documentation in Sentry's MDX stories format. Use when asked to "document a component", "add stories", "write component docs", "create an mdx file", "add a stories.mdx", or document a design system component. Generates structured MDX with live demos,…
  • 100testing
    Testing strategies for OCaml libraries. Use when discussing tests, alcotest, eio mocks, test structure, or test-driven development in OCaml projects.
  • 100local-geistdocs-92c51f3a
    Expert guidance for Geistdocs, Vercel's documentation template built with Next.js and Fumadocs — MDX authoring, configuration, AI chat, i18n, feedback, deployment. Use when creating documentation sites, configuring geistdocs, writing MDX content, or setting up docs infrastructure.
  • 100technical-docs
    Write and review technical documentation for Sentry SDK docs. Use when creating, editing, or reviewing documentation pages, especially MDX files in docs/platforms/.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.