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 ↗
- Repository
- ocaml-claude-marketplace ↗
- Licence
- ISC
- Last repository change
- 02.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.
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
- When to Use This Skill
- Overview
- File Structure
- .mld Format
- Tutorial Content Guidelines
- Verification
- Common Issues
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/.