01

The Big Idea

Why v2 exists and what it does differently

~3 min

What This Tool Does

Imagine pointing an AI at any codebase and getting back a beautiful, interactive course that teaches how that code works. That's what Codebase-to-Course does.
The original v1 (by Zara Zhang) had the AI generate the entire HTML file — all the styling, animations, quizzes, everything — in one massive output. It worked beautifully, but it was expensive.
💡
The v2 Insight

Why have the AI regenerate the same CSS and JavaScript every time? The styling never changes — only the content does. v2 separates them: the AI writes structured JSON, and a build script assembles the final HTML from pre-built templates. Result: 75% fewer tokens.

CODE
SKILL.md · lines 8-10
You do NOT generate HTML, CSS, or JavaScript.
You generate JSON that conforms to the course content schema.
The build script assembles the final course from your JSON + static templates.
PLAIN ENGLISH

The AI's job is content only — no visual code

Write structured data following the blueprint

A separate program handles all the visual assembly

v1 vs v2: The Key Difference

v1 approach (before) 
AI generates:
- Course content
- All HTML structure
- All CSS (1400 lines)
- All JavaScript (700 lines)
- Glossary tooltips

Total: ~25,000 tokens
v2 approach (after) 
AI generates:
- Course content as JSON

Build script handles:
- HTML (from template)
- CSS (from template)
- JavaScript (from template)
- Glossary injection

AI output: ~6,000 tokens
v1 makes the AI do everything. v2 makes the AI do only the creative work and automates the rest.

The Assembly Line

LLM
LLM (Claude)
SCH
JSON Schema
BLD
Build Script
TPL
Templates
OUT
HTML Output
Click "Next Step" to begin
Step 0 / 4
🧠 Check Your Understanding

What is the main difference between v1 and v2?

02

Meet the Players

The components that make v2 work

~3 min

The Cast of Characters

🤖
SKILL.md

The instruction manual for the AI — tells it how to analyze a codebase and generate content.

📐
JSON Schemas

Blueprints defining the exact shape of the AI's output — like a form with required fields.

🎨
Templates

Pre-built HTML, CSS, and JavaScript — the look, feel, and interactivity. Never change.

🔨
compile.js

The build script — takes JSON + templates and assembles the final course HTML.

CODE
build/compile.js · lines 506-528
function assembleSingleFile(courseData) {
  const baseHtml = loadTemplate('base.html');
  const css = loadTemplate('styles.css');
  const js = loadTemplate('scripts.js');
  html = html.replace('{{modules_content}}', modulesHtml);
PLAIN ENGLISH

The main assembly function — takes course data and produces one HTML file

Load the page skeleton template

Load all the visual styling

Load all the interactive behavior

Plug the rendered course modules into the page skeleton

File Structure

codebase-to-course-v2/
SKILL.mdAI instructions
schemas/
course-content.schema.jsonCourse data shape
codebase-profile.schema.jsonAnalysis data shape
templates/
base.htmlPage skeleton
styles.cssAll styling (1,391 lines)
scripts.jsAll interactivity (715 lines)
build/
compile.jsThe assembler (627 lines)

How They Talk

0 / 6 messages
🧠 Check Your Understanding
Scenario

You want to change the font used in all courses.

Which file would you edit?

03

The Build Pipeline

How compile.js turns JSON into a beautiful course

~3 min

The Assembly Process

1
Load & Parse

Read course-content.json and parse it into a JavaScript object.

2
Validate

Check every required field — title, actors, modules, quizzes. Report errors.

3
Render Modules

For each module, render each element using type-specific renderers.

4
Inject Glossary

Scan HTML for technical terms and wrap them in tooltip spans.

5
Assemble

Load base template, inject CSS, JS, nav, sidebar, and all modules. Write final file.

The Renderer Pattern

The build script has a renderer for each element type. When it sees {"type": "chat"}, it calls the chat renderer which knows how to turn that data into HTML.
CODE
build/compile.js · lines 161-163
const Renderers = {
  prose(el) {
    return `<div class="prose-block">${el.content}</div>`;
PLAIN ENGLISH

A collection of functions, one per element type

When the element type is 'prose'...

Wrap the content in a styled div

🧩
15 Element Types

prose, translation, chat, flow, callout, step_cards, pattern_cards, icon_rows, file_tree, architecture, badge_list, layer_toggle, spot_the_bug, diff_view, and custom_html.

Glossary Injection

CODE
build/compile.js · lines 132-156
const terms = Object.keys(glossary).sort((a, b) => b.length - a.length);
const regex = new RegExp(`(?<![<\\w])\\b(${escapedTerm})\\b`, 'i');
html = html.replace(regex, replacement);
PLAIN ENGLISH

Sort terms longest-first so 'JavaScript' matches before 'Java'

Find the term as a whole word, NOT inside HTML tags

Replace only the FIRST occurrence per module

🧠 Check Your Understanding

Why does the glossary sort terms longest-first?

04

Content Design Philosophy

Rules that make courses actually teach

~3 min

Who This Is For

The target learner is a vibe coder — someone who builds software by talking to AI, without a CS degree. They want to understand code well enough to steer AI better.
🎯

Steer AI Better

Know which components exist to direct AI precisely

🐛

Detect AI Mistakes

Spot hallucinations before they ship

🔧

Debug When Stuck

Escape AI bug loops by understanding what's happening

🗣️

Talk to Engineers

Learn vocabulary to describe requirements precisely

The Content Rules

✂️
Max 2-3 Sentences

Fourth sentence? Convert to a visual element.

👁️
50% Visual Minimum

Every screen must be at least half visual.

🎯
One Concept Per Screen

Need more space? Add another screen.

🎭
Unique Metaphors

Each concept gets its own metaphor. Never reuse.

📋
Original Code Only

Never modify snippets. Show real code as-is.

Module Curriculum Arc

CODE
SKILL.md · lines 86-97
| 1 | What the app does + trace a user action
| 2 | Meet the actors (components)
| 3 | How the pieces communicate
| 5 | Clever patterns
| 6 | When things break
PLAIN ENGLISH

Start concrete — what happens when someone uses it

Introduce the cast — which pieces exist

Data flow — debug 'not showing up' problems

Teach patterns learners can request from AI

Build debugging intuition

🧠 Check Your Understanding
Scenario

You've written 5 sentences explaining API authentication in Module 3.

What should you do?