Teach Me

# GitHub Pages Output Format

## File Structure

```
docs/
├── _config.yml
├── index.md
├── _tutorials/
│   ├── 01-getting-started.md
│   ├── 02-core-concepts.md
│   └── ...
├── _layouts/
│   ├── default.html          # Base layout
│   └── tutorial.html         # Tutorial page layout
├── _includes/
│   ├── nav.html              # Sidebar navigation
│   ├── progress.html         # Progress indicator
│   └── docs-link.html        # Official docs callout (for docs-sourced courses)
├── assets/css/
│   └── style.scss
└── _data/
    ├── tutorials.yml          # Tutorial metadata
    └── docs_map.yml           # Tutorial → docs page mapping (if docs-sourced)
```

## _config.yml

```yaml
title: "[Course Title]"
description: "[One-line course description]"
baseurl: "/repo-name"
source_docs: "https://docs.example.com"   # Optional: link to official docs
theme: null
plugins:
  - jekyll-seo-tag

collections:
  tutorials:
    output: true
    permalink: /tutorials/:slug/

defaults:
  - scope:
      path: ""
      type: tutorials
    values:
      layout: tutorial
```

## _data/tutorials.yml

```yaml
- number: 1
  title: "Write Your First Test"
  slug: "01-first-test"
  time: 20
  difficulty: beginner
  concepts: ["install", "first-test", "assertions"]
  prerequisites: []
  milestone: "Learner has a passing test suite"
  source_docs:                    # Only for docs-sourced courses
    - title: "Installation"
      url: "https://docs.example.com/install"
    - title: "Writing Tests"
      url: "https://docs.example.com/writing-tests"
  beyond_docs: "Explains project structure and config options the docs skip"
```

## Tutorial Front Matter

```yaml
---
layout: tutorial
title: "Write Your First Test"
number: 1
time: 20
difficulty: beginner
concepts: ["install", "first-test"]
prerequisites: []
milestone: "Learner has a passing test suite"
source_docs:
  - title: "Installation"
    url: "https://docs.example.com/install"
---
```

## _layouts/default.html Requirements

- Clean header with course title
- GitHub repo link (if applicable)
- Official docs link (if docs-sourced)
- Dark/light mode toggle using CSS `prefers-color-scheme` + JS toggle
- Footer with "Built with [tool name]" and links

## _layouts/tutorial.html Requirements

Must include these UI elements:

1. **Sidebar navigation** (left)
   - All tutorials listed
   - Current tutorial highlighted with accent
   - Difficulty dot (green/yellow/red) per tutorial
   - Time estimate per tutorial
   - Collapsible on mobile (hamburger menu)

2. **Progress bar** (top of main content)
   - "Tutorial X of N"
   - Visual progress bar

3. **Tutorial metadata** (below title)
   - Time badge
   - Difficulty badge
   - Prerequisites links

4. **Docs reference callout** (for docs-sourced courses)
   - Uses `_includes/docs-link.html`
   - Blue left-border box with link to source docs page

5. **Auto-generated TOC**
   - Generated from H2/H3 headings
   - Sticky on desktop, collapsible on mobile

6. **Previous / Next navigation** (bottom)
   - Shows tutorial titles, not just "Previous"/"Next"

7. **Syntax highlighting**
   - Via Rouge (built into Jekyll)
   - Line numbers for blocks > 5 lines

## _includes/docs-link.html

```html
{% if page.source_docs %}
<div class="docs-callout">
  <span class="docs-icon">📖</span>
  <div>
    <strong>Official Docs Reference</strong>
    {% for doc in page.source_docs %}
      <a href="{{ doc.url }}" target="_blank">{{ doc.title }} ↗</a>
    {% endfor %}
    <p>This tutorial goes deeper than the official docs.</p>
  </div>
</div>
{% endif %}
```

## assets/css/style.scss Requirements

- Professional color scheme (NOT default Jekyll theme)
- Suggested palette:
  - Primary: deep green (#2D8C3C) or blue (#2563EB)
  - Background: warm off-white (#FAFAF9) / dark (#111)
  - Code: dark (#1a1b26)
- Typography: system font stack or Google Fonts
- Code block styling with file-path labels
- Responsive sidebar (collapses at 768px)
- Progress bar styling
- Difficulty badge colors (green/yellow/red)
- Docs callout styling (blue left border)
- Mistake card styling (red/green split)
- Challenge card styling (amber background)
- Takeaways card styling (green background)
- Smooth transitions
- Print @media rules (hide nav, show all content)

## index.md Landing Page

```markdown
---
layout: default
title: Home
---

# [Course Title]

[Summary paragraph]

{% if site.source_docs %}
> 📖 This course is based on the [official documentation]({{ site.source_docs }})
> but reorganized as a progressive learning journey.
{% endif %}

## What You'll Build

[Progressive project description]

## Tutorials

{% for tutorial in site.data.tutorials %}
### {{ tutorial.number }}. [{{ tutorial.title }}]({{ site.baseurl }}/tutorials/{{ tutorial.slug }}/)
**{{ tutorial.time }} min** · {{ tutorial.difficulty | capitalize }}
{{ tutorial.milestone }}
{% endfor %}

## Start Learning

[Start with Tutorial 1 →]({{ site.baseurl }}/tutorials/{{ site.data.tutorials[0].slug }}/)
```

## Deployment

The user deploys by:
1. Pushing the `docs/` folder to their repo
2. Going to Settings → Pages → Source: `main` branch, `/docs` folder
3. The site is live at `https://username.github.io/repo-name/`