# Content Structure Reference

## trails.json Template

```json
[
  {
    "id": 1,
    "slug": "trail-slug",
    "title": "Trail Title",
    "subtitle": "Short subtitle explaining the trail (max 60 chars)",
    "description": "Longer description (1-2 sentences) of what students will learn.",
    "cover_image": "/covers/trail-01-slug.jpg",
    "color": "violet",
    "sort_order": 1,
    "total_modules": 2,
    "learning_objectives": [
      "Understand the fundamentals of X",
      "Be able to set up Y from scratch",
      "Apply Z to real-world scenarios"
    ]
  }
]
```

**Available Tailwind colors for trails**: violet, blue, emerald, amber, rose, indigo, cyan, orange, teal, pink, lime, sky

## modules.json Template

```json
[
  {
    "id": 1,
    "trail_id": 1,
    "slug": "m01-module-slug",
    "title": "Module Title",
    "description": "What this module covers (1-2 sentences).",
    "benefit": "What the student gains after completing this module",
    "icon": "emoji",
    "sort_order": 1,
    "total_lessons": 8,
    "learning_objectives": [
      "After this module you will be able to...",
      "You will understand how to..."
    ],
    "prerequisites": []
  }
]
```

**Module numbering**: `sort_order` must match the `m{NN}` prefix in lesson filenames. Module 1 = m01, Module 2 = m02, etc.

**Prerequisites**: Array of module IDs that must be completed first. Empty array = no prerequisites. Example: `"prerequisites": [1, 2]` means modules 1 and 2 must be done first.

## Lesson Markdown Template (v2)

Filename: `m{NN}-l{NN}-slug-in-kebab-case.md`

```markdown
# Modulo N — Licao M: Lesson Title

## O que voce vai aprender

- Objective 1: specific skill or knowledge you'll gain
- Objective 2: what you'll be able to DO after this lesson
- Objective 3: practical application

---

## Introducao

Hook paragraph that captures attention and sets expectations. Tell the student WHAT they'll learn and WHY it matters.

Use an analogy from everyday life to make the topic relatable.

---

## Section Title

Core content. Use:
- **Bold** for key terms (first mention only)
- Tables for comparisons
- Code blocks for technical examples
- Blockquotes for tips

> **Dica importante:** A practical tip formatted as blockquote

### Subsection (if needed)

More detailed content within the section.

---

## Another Section

Continue the lesson flow. Each section should build on the previous one.

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

---

## Exemplo Pratico

A hands-on example or case study relevant to the target audience.

```bash
# Command example (only when relevant)
echo "Hello World"
```

---

## Resumo

Brief recap of the key points:
- Key point 1
- Key point 2
- Key point 3

---

## Quiz Rapido

**1. [Question about a key concept from this lesson]**
- a) Wrong answer
- b) Correct answer ✓
- c) Wrong answer
- d) Wrong answer

**2. [Question about practical application]**
- a) Wrong answer
- b) Wrong answer
- c) Correct answer ✓
- d) Wrong answer

**3. [Question connecting theory to real life]**
- a) Correct answer ✓
- b) Wrong answer
- c) Wrong answer

---

## Checklist de Acao

- [ ] First practical action item
- [ ] Second action item
- [ ] Third action item
- [ ] Fourth action item (optional)
```

## New Sections (v2 additions)

### Learning Objectives (`## O que voce vai aprender`)
- MANDATORY in every lesson
- 2-4 objectives per lesson
- Written as "you will be able to..." statements
- Focus on what the student can DO, not just KNOW
- Parser extracts these into `lessons.learning_objectives` (JSON array)

### Quiz (`## Quiz Rapido`)
- MANDATORY in every lesson
- 3-5 multiple-choice questions
- Mix of conceptual and practical questions
- Correct answer marked with ` ✓` at the end
- Parser extracts into `quiz_questions` table

**Quiz parser regex patterns:**
```
Question: /^\*\*(\d+)\.\s*(.+?)\*\*$/m
Option: /^-\s+([a-d])\)\s*(.+?)(\s*✓)?$/m
Correct: option ends with ✓
```

### Summary (`## Resumo`)
- MANDATORY in every lesson
- 3-5 bullet points recapping key takeaways
- Written in active voice
- References practical applications

## Lesson Writing Guidelines

1. **Length**: 800-2000 words per lesson (sweet spot: ~1200 words)
2. **Sections**: 4-8 sections per lesson (including standard sections)
3. **Learning Objectives**: 2-4 at the top
4. **Quiz**: 3-5 questions after the summary
5. **Checklist**: 3-5 action items at the end
6. **Language**: PT-BR, informal but educational
7. **Analogies**: At least 1 per lesson connecting to everyday life
8. **Examples**: At least 1 practical example per lesson
9. **Code blocks**: Only when relevant — explain what it DOES, not line-by-line
10. **Progressive difficulty**: Each lesson builds on the previous within the module

## Content Quality Checklist

Before finalizing any lesson, verify:

- [ ] Title follows format: `# Modulo N — Licao M: Title`
- [ ] Learning objectives section present with 2-4 items
- [ ] Introduction has a hook and an analogy
- [ ] Content is 800-2000 words
- [ ] At least 1 practical example
- [ ] At least 1 analogy from everyday life
- [ ] Summary with 3-5 bullet points
- [ ] Quiz with 3-5 questions (correct answers marked with ✓)
- [ ] Checklist with 3-5 actionable items
- [ ] No jargon used without explanation
- [ ] Tone matches instructor persona
- [ ] No duplicate content from other lessons
- [ ] Sections separated by `---`
- [ ] Code blocks explained in simple language

## Content Planning Matrix

When planning a course, create a matrix:

| Trail | Module | Lesson # | Title | Key Concept | Difficulty | Est. Words |
|-------|--------|----------|-------|-------------|------------|------------|
| 1     | 1      | 1        | ...   | ...         | Beginner   | ~1200      |

### Difficulty levels:
- **Beginner**: No prior knowledge needed, heavy use of analogies
- **Intermediate**: Builds on previous lessons, practical applications
- **Advanced**: Complex concepts, multiple integrations, real-world scenarios

### Size targets:

| Size | Trails | Modules | Lessons | Total Words | Audio Hours |
|------|--------|---------|---------|-------------|-------------|
| Small | 4-5 | 8-12 | 60-100 | 72K-120K | 8-14h |
| Medium | 6-7 | 15-18 | 120-180 | 144K-216K | 16-25h |
| Large | 8-10 | 20-25 | 180-250 | 216K-300K | 25-35h |

## Filename Convention

```
m{NN}-l{NN}-slug-in-kebab-case.md
```

Examples:
```
m01-l01-introducao-ao-tema.md
m01-l02-conceitos-fundamentais.md
m01-l03-primeiro-exemplo-pratico.md
m02-l01-configurando-ambiente.md
m02-l02-instalacao-ferramentas.md
...
m22-l07-comunidade-onde-buscar.md
```

The parser regex: `/^m(\d{2})-l(\d{2})-(.+)\.md$/`
- `m(\d{2})` → module number (matches to modules.json sort_order)
- `l(\d{2})` → lesson number within module
- `(.+)` → slug for URL routing

## Section Parser Reference

The content-seed script should parse these sections from each lesson:

| Section | Parser | Database Field |
|---------|--------|----------------|
| `## O que voce vai aprender` | Extract `- ` items | `lessons.learning_objectives` (JSON) |
| `## Quiz Rapido` | Extract questions + options + correct | `quiz_questions` table |
| `## Checklist de Acao` | Extract `- [ ]` items | `checklist_items` table |
| Full content | Store as-is | `lessons.content_md` |
| Word count | `content.split(/\s+/).length` | `lessons.estimated_minutes` (÷ 200) |
