Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

tutorials

/tutorials

Tworzy samouczki bibliotek OCaml w formacie .mld z interaktywnymi przykładami MDX.

Licencja
ISC
Ostatnia zmiana repozytorium
02.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

ISC, otwarta.

Co robi i kiedy

Tworzy samouczki bibliotek OCaml w formacie .mld z interaktywnymi przykładami MDX.

Oryginalny opis (EN)

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

Jak działa

  1. When to Use This Skill
  2. Overview
  3. File Structure
  4. .mld Format
  5. Tutorial Content Guidelines
  6. Verification
  7. Common Issues
Sekcje z nagłówków SKILL.md, w oryginale · 188 linii, 504 słów
Podgląd SKILL.md
---
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.

Wersje

W bazie nie ma innych skilli o nazwie tutorials.

Migawka bazy z 13.11.2026 · wersja paczki d1a48a177c05 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100doc-style
    Ustala styl komentarzy OCaml i ocamldoc w tonie strony podręcznika POSIX, przy pisaniu, przeformułowywaniu, przeglądzie i usuwaniu komentarzy oraz dokumentacji .mli i .mld.
  • 100writing-tutorials
    Tworzy tutoriale dokumentacji Medusa w dwóch fazach: najpierw buduje funkcję w przykładowym projekcie (plan, kod, testy), potem pisze dokumentację MDX.
  • 100react-component-documentation
    Tworzy lub aktualizuje dokumentację komponentów w formacie MDX stories Sentry: żywe dema, wskazówki dostępności i automatyczna dokumentacja API z typów TypeScript.
  • 100testing
    Opisuje strategie testów bibliotek OCaml: strukturę testów, alcotest, mocki eio i rozwój oparty na testach.
  • 100local-geistdocs-92c51f3a
    Podpowiada, jak budować strony dokumentacji w Geistdocs na Next.js i Fumadocs: MDX, konfigurację, czat AI i wdrożenie.
  • 100technical-docs
    Pisze i recenzuje dokumentację techniczną SDK Sentry, zwłaszcza pliki MDX w docs/platforms.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.