# BYO Curriculum — Full Course (Single File)
> A self-directed research curriculum platform. Fork this template to create your own depth-first learning experience.
This document contains the complete course (7 clusters, 23 lessons) as a single plain-text file. It exists so that AI agents which only fetch one URL can still receive the entire course in one response.
- Course site: https://byocurriculum.dev
- Short index for agents: https://byocurriculum.dev/llms.txt
- Structured JSON API: https://byocurriculum.dev/api/curriculum.json?content=true
- Generated: 2026-08-04T19:39:52.559Z
## How To Help A User With This Course
When a user pastes this file (or shares a lesson URL) and asks for help:
1. Locate the lesson by title or by URL. Each lesson section below begins with a Lesson URL line.
2. Read the lesson's prose so you understand the framework it teaches. Stay faithful to the course's own framing instead of substituting generic advice.
3. Find the **Do This Now** subsection at the end of the lesson — that is the assignment.
4. Help the user actually do the assignment. Most assignments ask the user to produce something specific. Ask for the deliverable, task, or workflow they want to work on. Do not generate the artifact for them; help them produce it themselves.
5. If the lesson references external tools or companion apps, suggest them when relevant.
---
## Cluster 1: Getting Started (Foundation)
Cluster URL: https://byocurriculum.dev/curriculum/getting-started
Description: Why build a self-directed curriculum and how this platform works.
Before you dive into building your curriculum, it's worth understanding *why* this approach matters and how the platform is structured.
This cluster introduces the philosophy behind self-directed research curricula and gives you a technical overview of how everything fits together. By the end, you'll understand both the pedagogical motivation and the practical architecture.
### Lesson 1.1: Why Build a Self-Directed Curriculum
Lesson URL: https://byocurriculum.dev/curriculum/getting-started/why-curriculum
Description: The philosophy behind depth-first learning and why curated curricula matter more than ever.
## Welcome to Bring your Own Curriculum!
**You're about to build your own curriculum.** By the end of this guide, you'll have a live website where you can publish curated learning paths on any topic you're passionate about.
### What You'll Create
- A beautiful, responsive website for your curriculum
- A simple way to add and edit lessons
- Automatic deployment—edit content, and it goes live
- A structure that guides learners through foundational readings
### What You'll Need
This curriculum is designed for non-technical users. You'll need:
- **A computer** with internet access
- **An email address** for creating free accounts
- **A topic you're passionate about** (philosophy, design, history, anything!)
- **About 2-3 hours** spread across multiple sessions
No coding experience required. If you can fill out web forms and follow step-by-step instructions, you can do this.
### How This Curriculum Is Organized
| Cluster | What You'll Learn |
| --- | --- |
| **Getting Started** | Why curricula matter, how the platform works |
| **Building Your Curriculum** | Define your topic, find readings, structure content |
| **Deployment & Setup** | Get your site live, set up the CMS |
| **Working With Content** | Edit via browser or locally |
| **Making It Yours** | Customize colors, fonts, and styling |
Work through the clusters in order. Each builds on the previous one.
---
## The Case for Self-Directed Curricula
We're living through a fundamental shift in how knowledge is created and consumed. AI can now generate passable summaries of almost any topic. Search engines surface millions of results for any query. Content mills produce endless "ultimate guides" and "everything you need to know" articles.
In this environment, surface-level knowledge has been commoditized. What remains valuable is _genuine expertise_—the kind that comes from actually engaging with primary sources, struggling with difficult ideas, and forming original perspectives.
This is what a self-directed curriculum provides: a structured path to depth.
## Why "Self-Directed"?
The term "self-directed" doesn't mean you're alone. It means you're taking ownership of your learning—choosing what to study, setting your own pace, and engaging actively with the material rather than passively absorbing it.
A self-directed curriculum is like having a thoughtful mentor who says: "Here are the texts that shaped this field. Here's a sensible order to read them. Here are the key ideas to focus on. Now go do the work."
The curriculum provides structure. You provide the engagement.
## What This Platform Enables
This platform lets you create that structured path for yourself or others. Whether you're:
- **Learning a new field** and want to identify the foundational texts
- **Teaching** and want to provide students with a clear reading path
- **Building expertise** and want to document your learning journey
- **Sharing knowledge** with a community around a specific domain
The curriculum format—clusters of related lessons, each built around primary readings—provides the scaffolding for serious intellectual work.
## The Meta-Curriculum
What you're reading right now is a curriculum _about building curricula_. It demonstrates the format while teaching you how to create your own.
By the time you finish these lessons, you'll have:
1. A clear understanding of why this approach works
2. The methodology for defining your own curriculum
3. The technical knowledge to deploy and maintain it
Let's begin.
---
### Lesson 1.2: How This Platform Works
Lesson URL: https://byocurriculum.dev/curriculum/getting-started/platform-architecture
Description: Technical overview of the curriculum platform: content structure, CMS, and deployment.
## Platform Architecture
This platform is built with simplicity and longevity in mind. Here's how the pieces fit together:
### Content Storage
All content lives in the `/content` directory as plain Markdown files:
```plain
content/
├── clusters/ # Cluster definitions
│ ├── getting-started.md
│ └── building-curriculum.md
├── lessons/ # Individual lessons
│ ├── getting-started-why-curriculum.md
│ └── getting-started-platform-architecture.md
├── pages/ # Static pages (home, about)
│ ├── home.md
│ └── about.md
└── settings/ # Site configuration
└── site.json
```
Each file combines YAML frontmatter (structured data) with Markdown content (prose). This means your entire curriculum is portable, version-controlled, and readable without any special tools.
### The Build Process
When you deploy, the platform:
1. Reads all Markdown files from `/content`
2. Validates the content against expected fields
3. Builds a static website with all your lessons
4. Deploys to Netlify's global CDN
The result is a fast, secure, static site with no database or server to maintain.
### The CMS Interface
While you _can_ edit Markdown files directly, the CMS provides a friendlier interface:
- **Visual forms** for each field (title, description, etc.)
- **Rich text editing** for lesson content
- **Relationship fields** to link lessons to clusters
- **Image uploads** that go directly to your repository
The CMS is powered by [Sveltia CMS](https://github.com/sveltia/sveltia-cms), an open-source Git-based CMS. When you save changes, it commits them to your GitHub repository—no separate database required.
### Technology Stack
For the technically curious:
- **Framework**: SvelteKit (fast, modern, great developer experience)
- **Styling**: CSS Custom Properties for easy theming
- **CMS**: Sveltia CMS (Git-based, no backend needed)
- **Hosting**: Netlify (free tier handles most curricula)
- **Auth**: GitHub OAuth via Cloudflare Workers
The entire stack is free or very low cost for typical usage.
## Key Files to Know
| File | Purpose |
| --- | --- |
| `static/admin/config.template.yml` | CMS schema definition (config generated at build time) |
| `content/settings/site.json` | Site title, description, author |
| `content/pages/home.md` | Homepage content |
| `src/app.css` | Color, font, and theme customization |
You'll interact with these files when customizing your curriculum. The following lessons will walk you through each one.
## What You Don't Need to Worry About
This platform handles the technical complexity so you can focus on content:
- **No server management**: Everything runs on Netlify's free tier
- **No database**: Content is stored as files in your repository
- **No deployment scripts**: Push to GitHub, site updates automatically
- **No coding required**: The CMS handles content editing visually
You _can_ customize the code if you want to, but it's entirely optional.
---
## Cluster 2: Building with AI (Foundation)
Cluster URL: https://byocurriculum.dev/curriculum/building-curriculum
Description: Use AI prompts to define your domain, discover readings, and auto-populate your curriculum.
This is the AI-assisted path for building your curriculum. If you're comfortable using Claude, GPT-4, or similar tools, this approach lets you generate a complete first draft quickly—then refine it over time.
The lessons walk you through using specific prompts to define your field, discover foundational readings, structure everything into clusters, and auto-populate your CMS. Each lesson includes the actual prompts you'll use, along with explanations of why they work.
**Not comfortable with AI tools?** See the [Building Manually](/curriculum/building-manually) cluster for a traditional approach.
### Lesson 2.1: Defining Your Domain
Lesson URL: https://byocurriculum.dev/curriculum/building-curriculum/defining-domain
Description: Use AI prompts to articulate your curriculum's scope, central questions, and boundaries.
## The Art of Domain Definition
**_Prefer working without AI?_** See the [Building Manually](/curriculum/building-manually) cluster for a hands-on approach.
The most common mistake in curriculum design is being too broad. "A curriculum on philosophy" is too broad. "A curriculum on how 20th-century analytic philosophy addressed the mind-body problem" is focused enough to be useful.
## The Domain Definition Prompt
Here's the prompt you'll use. It's also available as a standalone file at `/prompts/01-domain-definition.md`:
```markdown
I want to build a self-directed research curriculum on [YOUR DOMAIN].
Please help me define this curriculum by addressing:
1. **Central Question**: What is the core question this curriculum helps answer? Frame it as: "What will someone who completes this be able to understand or do?"
2. **Scope Definition**:
- What specific aspects of [YOUR DOMAIN] should be included?
- What should be explicitly excluded to maintain focus?
- What level of depth are we aiming for?
3. **Intellectual Traditions**:
- What schools of thought or academic disciplines inform this domain?
- Who are the foundational thinkers?
- What are the key debates or tensions within the field?
4. **Audience**:
- What prior knowledge should learners have?
- What are they likely trying to achieve?
5. **Success Criteria**: How would someone know they've "completed" this curriculum? What would they be able to do or discuss?
Please be specific and opinionated. I want a focused curriculum, not a comprehensive survey.
```
Run this prompt, then review the output carefully. Ask follow-up questions to refine the framing.
## Example: A Curriculum on "Device Theory"
Here's how domain definition worked for a curriculum on how material, conceptual, and ritual instruments shape human reality:
**Central Question**: How do devices—material, conceptual, and ritual—mediate human experience and become naturalized as "just how things are"?
**Scope**:
- Included: Social construction theory, media ecology, ritual studies, technology philosophy
- Excluded: Technical implementation, specific technologies, historical surveys
**Traditions**: Phenomenology (Heidegger), sociology of knowledge (Berger/Luckmann), media theory (McLuhan), ritual studies (Bell)
**Audience**: Researchers, designers, and thinkers interested in how technologies shape society—not technologists themselves.
This focused definition made it possible to curate 25 meaningful lessons rather than 100 superficial ones.
---
### Lesson 2.2: Finding Foundational Readings
Lesson URL: https://byocurriculum.dev/curriculum/building-curriculum/finding-readings
Description: Use AI prompts to discover the canonical texts and influential works in your domain.
## Finding the Right Readings
The quality of your curriculum depends on the quality of your readings. Surface-level content produces surface-level learning. Foundational texts—the ones that shaped how people think about a domain—produce genuine understanding.
## The Reading Discovery Prompt
Here's the prompt for discovering foundational readings. It's also available at `/prompts/02-reading-discovery.md`:
```markdown
I'm building a self-directed research curriculum on [YOUR DOMAIN].
The central question is: [YOUR CENTRAL QUESTION FROM LESSON 1]
The scope includes: [YOUR SCOPE DEFINITION]
Please suggest foundational readings for this curriculum. For each reading, provide:
1. **Full citation** (author, title, year, publisher if book)
2. **Why it's foundational** (what key ideas it introduces)
3. **What cluster/theme** it might belong to
4. **Prerequisites** (what should be read first, if any)
5. **Difficulty level** (accessible, moderate, challenging)
Prioritize:
- Primary sources over secondary sources
- Texts that introduced key concepts
- Works that are frequently cited in the field
- Readings that reward close engagement
Suggest 15-25 readings organized by theme.
IMPORTANT: Only suggest texts you're confident actually exist. I will verify all citations.
```
## Evaluating the Results
When you get the AI's suggestions:
1. **Verify existence**: Search for each text on Google Scholar or WorldCat. AI can invent plausible-sounding titles.
2. **Check accessibility**: Can you actually get the text? Look for:
- Internet Archive (free borrowing)
- Library access
- Open access versions
- Legal PDFs
3. **Assess centrality**: How often is this text cited by the other suggested texts? Highly-cited texts are more central.
4. **Consider diversity**: Does the list represent multiple perspectives? Different time periods? Varied methodological approaches?
5. **Trust your judgment**: If you know the field, you'll recognize gaps or questionable inclusions. The AI is a starting point.
## Organizing by Theme
As you evaluate readings, patterns will emerge. You might notice:
- Several texts address the same fundamental concept
- Some texts naturally precede others
- Distinct "schools of thought" become visible
These patterns suggest your cluster structure. Group related readings, and you'll start to see your curriculum take shape.
## Example: Organizing Readings
Readings often naturally group into themes. For example, a curriculum on social theory might organize like this:
| Cluster | Theme | Key Texts |
|---------|-------|-----------|
| Foundations | Core theoretical frameworks | Foundational authors in the field |
| Methods | How to apply the theory | Methodological texts |
| Applications | Theory in practice | Case studies and examples |
| Critiques | Challenges and alternatives | Responses and revisions |
This structure should emerge from the readings themselves, not from an abstract plan.
## Quality Over Quantity
Resist the temptation to include too many readings. Each lesson should center on one primary reading that rewards careful engagement. A curriculum of 15-25 deep readings produces better learning than 50 skimmed articles.
Ask: "Is this text essential enough that someone couldn't claim expertise without having read it?"
If the answer is "no," consider cutting it or moving it to additional resources.
---
### Lesson 2.3: Structuring Into Clusters and Lessons
Lesson URL: https://byocurriculum.dev/curriculum/building-curriculum/structuring-content
Description: Transform your reading list into a coherent curriculum structure with logical progression.
## From Readings to Structure
You have your domain definition and a list of foundational readings. Now comes the creative work: transforming that list into a curriculum learners can actually follow.
## The Curriculum Structure Prompt
Use this prompt to generate your curriculum structure. It's also at `/prompts/03-curriculum-structure.md`:
```markdown
I have a reading list for my curriculum on [YOUR DOMAIN].
Here are the readings I've selected:
[PASTE YOUR READING LIST FROM LESSON 2]
Please help me structure these into a curriculum by:
1. **Grouping into clusters**: Identify 3-7 thematic groupings. For each cluster, provide:
- Title
- Description (1-2 sentences)
- Which readings belong to it
- Suggested order of readings within the cluster
2. **Sequencing clusters**: What order should clusters appear in? Why?
3. **Identifying dependencies**: Which readings require prior readings? Are there any prerequisite relationships?
4. **Suggesting additions or cuts**: Based on the structure, are there:
- Gaps that need filling?
- Redundancies that could be cut?
- Readings that don't fit?
5. **For each reading, draft**:
- Description (1-2 sentences on why it matters)
- 3-5 key concepts to focus on
- 2-3 knowledge check questions
Make the curriculum progressively complex: foundations first, specialized applications later.
```
## Cluster Design Principles
As you review the AI's suggested structure:
### Unity
Each cluster should have a clear, articulable theme. If you can't explain what unifies the lessons in a sentence, the cluster needs rework.
### Progression
Lessons within a cluster should build on each other. The first lesson establishes concepts; later lessons deepen them.
### Independence
While clusters build on each other, each should deliver standalone value. Someone reading just one cluster should learn something complete.
### Size
Aim for 2-5 lessons per cluster. Fewer than 2 suggests the theme isn't substantial enough. More than 5 suggests it should be split.
## Lesson Structure Deep Dive
Each lesson needs:
### Introduction (body field)
Context for why this reading matters. Connect it to the curriculum's central question. Explain what the reader will gain.
### Key Concepts (key_concepts field)
3-5 ideas the reader should focus on. These aren't summaries—they're signposts that help readers know what to pay attention to.
### Assignment (assignment field)
The primary reading with:
- Clear instructions
- Link to access the text
- Expected time investment (if known)
### Knowledge Check (knowledge_check field)
2-4 reflection questions. Good questions:
- Can't be answered without doing the reading
- Encourage synthesis, not recall
- Connect to broader curriculum themes
### Additional Resources (additional_resources field)
Optional further reading for those who want to go deeper. Not required for completion.
## Example: Structuring a Cluster
Here's how the "Reality Construction" cluster was structured:
**Cluster**: Reality Construction & Media Devices
**Theme**: How media shapes our perception of what's real
| Order | Reading | Why This Sequence |
|-------|---------|-------------------|
| 1 | Berger & Luckmann | Establishes basic framework of social construction |
| 2 | Searle | Adds institutional facts and collective intentionality |
| 3 | Lippmann | Applies construction theory to media/public opinion |
Each reading builds on vocabulary and concepts from the previous one. By the end, learners can analyze how media constructs social reality—a synthesis of all three texts.
## Final Review
Before finalizing your structure:
1. **Read it as a learner**: Does the progression make sense?
2. **Check prerequisites**: Can every lesson be understood with what came before?
3. **Verify access**: Can learners actually get each reading?
4. **Test the time**: Is the overall scope achievable?
Now you're ready to create your content files and deploy.
---
### Lesson 2.4: Auto-Populating Your CMS
Lesson URL: https://byocurriculum.dev/curriculum/building-curriculum/auto-populate
Description: Use AI to generate complete lesson content and batch-populate your curriculum for first deployment.
## The Case for Batch Generation
Many curriculum creators stall at content creation. Defining the domain is exciting. Finding readings feels productive. But sitting down to write 20+ lessons? That's where projects die.
Batch generation solves this by giving you something to edit instead of a blank page. A mediocre first draft you can improve beats no draft at all.
## The Lesson Generation Prompt
Use this prompt for each cluster of readings:
```markdown
I'm building a self-directed research curriculum on [YOUR DOMAIN].
Here are readings for the "[CLUSTER NAME]" cluster:
1. [READING 1 - Author, Title, Year]
2. [READING 2 - Author, Title, Year]
3. [READING 3 - Author, Title, Year]
For each reading, generate a complete lesson with:
## Lesson: [Title]
**slug**: [url-friendly-version]
**description**: [1-2 sentences on why this reading matters]
**key_concepts**:
- name: "[Concept 1]"
explanation: |
[2-3 paragraphs explaining this concept]
- name: "[Concept 2]"
explanation: |
[2-3 paragraphs explaining this concept]
- name: "[Concept 3]"
explanation: |
[2-3 paragraphs explaining this concept]
**assignment**:
instructions: |
[Clear instructions for engaging with the reading]
url: [Link to access the reading, if known]
reading_title: "[Full citation]"
**knowledge_check**:
- question: "[Reflection question 1]"
hint: "[Hint to guide thinking]"
- question: "[Reflection question 2]"
hint: "[Hint to guide thinking]"
**body**: |
[2-4 paragraphs introducing the reading, its context,
why it matters for the curriculum, and what to pay attention to]
---
Make explanations accessible to someone new to the field.
Focus on what makes each reading foundational, not just what it contains.
```
## Entering Content into the CMS
### Step 1: Create Your Clusters First
1. Go to `your-site.netlify.app/admin/`
2. Navigate to "Clusters" in the sidebar
3. Create each cluster with title, slug, description, and order
4. Save each one before moving on
### Step 2: Add Lessons to Each Cluster
For each generated lesson:
1. Click "Lessons" → "New Lesson"
2. Fill in basic fields:
- **Title**: From your AI output
- **Slug**: URL-friendly version (e.g., `social-construction`)
- **Cluster**: Select from dropdown
- **Order**: Position within cluster
- **Description**: 1-2 sentence summary
3. Add key concepts:
- Click "Add key concept"
- Paste name and explanation
- Repeat for each concept
4. Add assignment:
- Paste instructions
- Add reading URL if available
- Add reading title
5. Add knowledge check:
- Click "Add question"
- Paste question and hint
- Repeat for each question
6. Add body content:
- Paste the introduction/context paragraphs
- This appears at the top of the lesson page
7. **Save** → Triggers automatic deployment
### Step 3: Batch Your Work
Don't try to perfect each lesson as you enter it. Instead:
- **First pass**: Enter all content quickly
- **Second pass**: Review and fix obvious errors
- **Ongoing**: Refine individual lessons over time
A complete curriculum with rough edges beats three perfect lessons and seventeen empty placeholders.
## Example: Generated Lesson
Here's what AI-generated content might look like for a social theory curriculum:
**Input**: "Berger & Luckmann - The Social Construction of Reality (1966)"
**Output**:
```yaml
title: The Social Construction of Reality
slug: social-construction-reality
description: "The foundational text on how societies create and maintain shared reality through ongoing interaction."
key_concepts:
- name: "Externalization, Objectivation, Internalization"
explanation: |
Berger and Luckmann describe a three-step process by which human activity becomes social reality...
- name: "Institutional Facts"
explanation: |
Some facts exist only because we collectively agree they do...
assignment:
instructions: |
Read Part I of The Social Construction of Reality, focusing on the dialectical relationship between humans and social reality...
url: "https://archive.org/details/..."
reading_title: "Berger, P. & Luckmann, T. (1966). The Social Construction of Reality. Anchor Books."
knowledge_check:
- question: "How does 'objectivation' transform human activity into something that feels external and given?"
hint: "Think about how habits become institutions."
body: |
Published in 1966, The Social Construction of Reality became one of the most influential works in sociology...
```
This output is ready to paste into your CMS fields.
## Handling Multiple Readings
For efficiency, generate 3-5 lessons per prompt. More than that and quality drops. Structure your session:
| Time | Activity |
|------|----------|
| 10 min | Generate lessons for Cluster 1 |
| 15 min | Enter Cluster 1 into CMS |
| 10 min | Generate lessons for Cluster 2 |
| 15 min | Enter Cluster 2 into CMS |
| ... | Continue for remaining clusters |
A 5-cluster curriculum with 3 lessons each takes roughly 2-3 hours to fully populate.
## What Comes Next
Your curriculum is now live but imperfect. That's exactly right.
The next lesson covers how to refine AI-generated content over time—fixing explanations, adding your perspective, improving based on feedback. The goal was never to publish AI content directly. It was to have something real to improve.
---
### Lesson 2.5: Refining AI-Generated Content
Lesson URL: https://byocurriculum.dev/curriculum/building-curriculum/refining-content
Description: Improve your auto-generated curriculum over time with targeted edits and your unique perspective.
## The Refinement Mindset
You now have a complete curriculum. It's live. People can use it. And it's not perfect.
This is exactly where you should be.
The refinement phase is where your curriculum becomes genuinely valuable. AI gave you structure and competent explanations. You add the perspective, judgment, and voice that make it worth reading.
## Prioritizing What to Fix
### The Impact Matrix
| Lesson Type | Refinement Priority | Why |
|-------------|---------------------|-----|
| Cluster 1, Lesson 1 | **Highest** | First impression, sets expectations |
| Foundation lessons | **High** | Vocabulary established here carries forward |
| Most-visited lessons | **High** | Actual user value |
| Dense/complex topics | **Medium** | Generic explanations hurt most here |
| Later specialized lessons | **Lower** | Readers who get here are already invested |
Don't refine in order. Refine by impact.
### Quick Wins First
Some fixes take 2 minutes and significantly improve quality:
- **Fix broken links**: Nothing kills credibility faster
- **Add a specific example**: Replace "for instance, in many fields..." with a real case
- **Cut hedging**: "It might be argued" → just state the point
- **Add a sentence of context**: "This matters because..."
Do these first. Save deep rewrites for later.
## Adding Your Perspective
### The Personal Insert
For each lesson, add at least one moment of genuine perspective:
**Before (AI-generated)**:
> "Berger and Luckmann's concept of institutionalization has been influential in sociology and related fields."
**After (with your voice)**:
> "Berger and Luckmann's concept of institutionalization changed how I think about organizational culture. When I see a company's 'way we do things,' I now ask: what repeated actions became habits, then rules, then 'just how things are'? The process is invisible until you have vocabulary for it."
The addition is small but transforms the lesson from summary to insight.
### Where to Add Voice
- **Introduction**: Why *you* chose this reading
- **Key concepts**: What *you* think is most important
- **Assignment instructions**: How *you* recommend approaching it
- **Knowledge check hints**: What *you* found helpful to focus on
You don't need to add personal perspective everywhere. One or two moments per lesson is enough to make it feel authored, not generated.
## Common Refinements
### Generic → Specific
**Before**: "This concept appears in many contexts."
**After**: "This concept explains why design systems feel constraining at first but liberating once internalized—the initial friction is institutionalization in progress."
### Abstract → Concrete
**Before**: "The author argues that social facts constrain individual behavior."
**After**: "Think about money. A $20 bill is paper. Its value exists only because we collectively agree it does. You can't individually decide it's worth $100. That's a social fact constraining your behavior—and you barely notice it."
### Passive → Active
**Before**: "It has been suggested that media shapes perception."
**After**: "Lippmann argues that we don't react to the world—we react to 'pictures in our heads' that media creates. The news doesn't inform you about the world; it constructs the world you think you know."
## The Weekly Refinement Practice
Build a sustainable habit:
### Monday: Review One Lesson (15 min)
- Read through as if you're a new learner
- Note anything that confuses or feels flat
- Don't fix yet—just note
### Wednesday: Make One Improvement (20 min)
- Pick the most impactful issue from Monday
- Rewrite that section
- Save and publish
### Friday: Verify (5 min)
- Check that your change deployed
- Click through any links you touched
- Done for the week
This cadence means 52 improvements per year. After a year, your curriculum is genuinely refined—and you never burned out doing it.
## When to Stop Refining
Some lessons will never feel perfect. That's fine.
Stop refining a lesson when:
- You've added your perspective to key sections
- All links work and citations are verified
- The explanation is clear to your target audience
- You've read through it twice without finding issues
Move on. The remaining imperfections are less costly than the refinements you could make elsewhere.
## The Living Curriculum
A curriculum isn't a document you finish. It's a practice you maintain.
As you learn more, add it. As readers give feedback, respond. As the field evolves, update. The AI gave you a starting point. Everything from here is yours.
---
## Cluster 3: Building Manually (Foundation)
Cluster URL: https://byocurriculum.dev/curriculum/building-manually
Description: Create your curriculum through careful curation and direct CMS entry—no AI required.
This is the traditional path for building your curriculum. If you prefer working without AI tools, or want more hands-on control over every word, this approach guides you through the process step by step.
You'll learn how to identify the readings that matter most, understand exactly what each CMS field is for, and build your curriculum through thoughtful curation rather than generation.
**Comfortable with AI tools?** See the [Building with AI](/curriculum/building-curriculum) cluster for a faster approach.
### Lesson 3.1: Choosing Your Research Topic
Lesson URL: https://byocurriculum.dev/curriculum/building-manually/choosing-topic
Description: What kinds of topics work best for this platform, and how to scope yours appropriately.
## Finding the Right Topic
**_Prefer AI assistance?_** See the [Building with AI](/curriculum/building-curriculum) cluster for a prompt-based approach.
The most common mistake is choosing a topic that's too broad. "Philosophy" isn't a topic—it's an entire discipline. "How 20th-century phenomenology shaped human-computer interaction" is a topic.
## Questions to Ask Yourself
### 1. Can I Name the Canon?
For any well-established intellectual domain, there's a rough canon—the works that everyone in the field has read or at least knows they should read.
- In social construction theory: Berger & Luckmann, Searle, Douglas
- In media ecology: McLuhan, Postman, Ong
- In design thinking: Norman, Cross, Schön
If you can rattle off 5-10 names that "everyone in the field knows," your topic has the infrastructure for a research curriculum.
If you struggle to name foundational works, either:
- The field is too new to have a canon
- The field is too broad (you're thinking of a discipline, not a topic)
- You may not know the field as well as you thought
### 2. Do the Sources Reward Close Reading?
Some texts are meant to be read once for information. Others reveal more each time you return to them.
Research curricula work best with texts that:
- Have density that rewards slow reading
- Contain ideas that connect to other texts
- Provoke questions that send you elsewhere
- Remain relevant despite being older
Popular science books, how-to guides, and news articles rarely have these qualities. Classic monographs, foundational papers, and theoretical works often do.
### 3. What's Your Entry Point?
You don't need to be the world's leading expert. But you do need:
- **Personal engagement**: You've read the core texts yourself
- **A perspective**: You have views on what matters and why
- **Enough distance**: You can see the field, not just your position in it
If you're just starting to explore a topic, that's fine—but consider building the curriculum *as* you learn, adding lessons as you complete readings yourself.
## Scoping Your Curriculum
### Too Broad
"A curriculum on sociology"
Problems:
- No clear endpoint
- Too many foundational texts to include
- No coherent central question
### Too Narrow
"A curriculum on chapter 3 of Being and Time"
Problems:
- Not enough material for multiple lessons
- Learners need broader context
- Feels incomplete
### Just Right
"A curriculum on how Heidegger's tool analysis applies to digital technology"
Why it works:
- Clear central question
- Identifiable foundational texts (Heidegger, plus technology philosophers who build on him)
- Specific enough to complete, broad enough to be valuable
- Has practical relevance while maintaining theoretical depth
## Examples of Good Topics
| Topic | Why It Works |
|-------|--------------|
| Social construction of technology | Clear lineage from Berger/Luckmann through SCOT theorists |
| Ritual and habit formation | Draws from Bell, Bourdieu, clear primary sources |
| Philosophy of information | Floridi and predecessors, defined field with canon |
| Media effects on cognition | McLuhan through Carr, established debates |
| Organizational sensemaking | Weick's work plus extensions, clear theoretical tradition |
## Examples of Topics That Need Refocusing
| Original Topic | Problem | Refocused Version |
|---------------|---------|-------------------|
| "Technology ethics" | Too broad, no canon | "How virtue ethics applies to algorithmic decision-making" |
| "Leadership" | Too applied/practical | "Theories of distributed cognition in teams" |
| "AI" | Too current, moving target | "Historical philosophy of machine intelligence" |
| "My productivity system" | Too personal | "Theories of attention and deep work" |
## Ready to Proceed?
Once you can confidently describe:
- Your topic in one sentence
- 10-15 foundational texts
- Why this topic rewards depth
You're ready to identify your core readings and start building.
---
### Lesson 3.2: Identifying Your Core Readings
Lesson URL: https://byocurriculum.dev/curriculum/building-manually/core-readings
Description: How to select foundational texts without AI assistance—using your judgment and research skills.
## Building Your Reading List
Without AI to generate suggestions, you'll build your reading list through deliberate research. This takes more time but often produces better results—you understand why each text is included because you found it yourself.
## Starting Points
### What You Already Know
If you've studied this topic, you already have opinions about what matters. Start there:
- What texts shaped your understanding?
- What do experts in the field constantly reference?
- What books sit on your shelf because they're essential?
Write these down before researching further. Your intuitions are valuable.
### Academic Literature
For established fields, academic publishing provides a roadmap:
1. **Google Scholar**: Search your topic + "foundational" or "canonical" or "seminal"
2. **Citation counts**: Highly-cited works have influenced the field
3. **Review articles**: Literature reviews often name the essential texts
4. **Syllabi**: Search "[topic] syllabus" to see what professors assign
### Expert Communities
People who work in the field know what matters:
- **Ask directly**: Email a professor, post in a forum
- **Twitter/academic social media**: Scholars often discuss canonical works
- **Podcast interviews**: Experts frequently name influential readings
- **"What should I read?" threads**: Reddit, Discord, and forums have these
## Evaluating Candidates
For each potential reading, ask:
### Is it primary or secondary?
| Type | Include as... |
|------|---------------|
| Original theoretical work | Core lesson reading |
| Commentary or explanation | Additional resource |
| Textbook summary | Generally skip |
| Popular translation of ideas | Additional resource at most |
### How influential is it?
Check Google Scholar citation count as a rough guide:
| Citation Count | What It Suggests |
|----------------|------------------|
| 10,000+ | Major foundational work |
| 1,000-10,000 | Significant in the field |
| 100-1,000 | Specialized but respected |
| Under 100 | May be too niche or too new |
These numbers vary by field—philosophy has lower counts than psychology. Compare to other works in your topic.
### Can learners access it?
| Source | Accessibility |
|--------|---------------|
| Internet Archive | Free borrowing for 14 days |
| Open access repository | Free permanent access |
| Library (physical or digital) | Free with membership |
| In-print book ($15-30) | Accessible to most |
| Out-of-print ($50+) | Barrier for many learners |
| Behind expensive paywall | Likely exclude |
Don't make learners hunt or pay unreasonable amounts.
### Does it fit the conversation?
Your readings should be in dialogue with each other:
- Does this text reference others in your list?
- Is it referenced by others in your list?
- Does it address your central question?
- Does it use vocabulary established by other readings?
Outliers may be interesting but weaken curriculum coherence.
## Organizing into Clusters
As you gather readings, patterns emerge:
### Natural Groupings
Readings often cluster around:
- **Foundational concepts**: The basic vocabulary and frameworks
- **Historical development**: How ideas evolved over time
- **Different perspectives**: Schools of thought or methodological approaches
- **Applications**: How theory applies to specific contexts
- **Critiques**: Challenges and responses to core ideas
### Sequencing
Within and across clusters, consider:
1. **Concept dependencies**: Which ideas require understanding others first?
2. **Chronology**: Earlier works often define terms later works use
3. **Difficulty**: Accessible texts before dense ones
4. **Motivation**: Put engaging readings early to build momentum
## Example: Building a Social Theory List
### Step 1: Starting intuitions
- Berger & Luckmann (I know this is foundational)
- Douglas's "How Institutions Think" (Referenced constantly)
- Searle on social facts (Builds on Berger)
### Step 2: Citation research
- Google Scholar shows these are all highly cited
- Bibliographies repeatedly reference Schutz, Durkheim, Weber
- Add these as potential earlier foundations
### Step 3: Access check
- Berger & Luckmann: Internet Archive ✓
- Douglas: In print, $18 ✓
- Searle: Library access ✓
- Schutz: Academic paywall ✗ (move to additional resources)
### Step 4: Organization
- **Cluster 1**: Foundations (Durkheim excerpt, Weber excerpt)
- **Cluster 2**: Social Construction (Berger & Luckmann, Searle)
- **Cluster 3**: Institutional Analysis (Douglas)
## Final Checklist
Before moving on:
- [ ] 10-20 readings identified
- [ ] Each text verified as accessible
- [ ] Natural thematic clusters visible
- [ ] Readings form coherent intellectual conversation
- [ ] You can explain why each text is included
---
### Lesson 3.3: Understanding the CMS Fields
Lesson URL: https://byocurriculum.dev/curriculum/building-manually/cms-fields
Description: What each field in the CMS does, which are required, and what to keep in mind when filling them.
## CMS Field Reference
This is your complete guide to every field in the lesson editor. Keep this open as you create content.
---
## Flexible Content Structure
**You control what appears on each lesson page.** Only 5 metadata fields are required—everything else is optional and won't render if left empty.
This means you can create:
- **Minimal lessons**: Just a title, description, intro, and reading link
- **Full lessons**: All sections filled with rich content blocks
- **Anything in between**: Mix and match based on what each reading needs
Content Blocks are flexible—add objectives, concepts, questions, resources, and callouts in any order. If you don't add any blocks, that section simply won't appear. The page adapts to whatever content you provide.
---
## Required Fields
These fields must be filled for the lesson to function.
### Title
**What it is**: The lesson name displayed on the site
**Best practices**:
- Be descriptive but concise (5-10 words)
- Use title case: "The Social Construction of Reality"
- Don't include lesson numbers—order is handled separately
**Examples**:
- ✓ "Finding Foundational Readings"
- ✓ "How Institutions Shape Thought"
- ✗ "Lesson 3: Readings" (too vague, includes number)
- ✗ "THE SOCIAL CONSTRUCTION OF REALITY CHAPTER ONE" (too long, all caps)
### Slug
**What it is**: The URL-friendly identifier for this lesson
**Best practices**:
- Lowercase letters and hyphens only
- No spaces, underscores, or special characters
- Keep it short but recognizable
- Never change after publishing
**Examples**:
- ✓ `social-construction`
- ✓ `finding-readings`
- ✗ `Social Construction` (spaces, caps)
- ✗ `lesson_3` (underscore, not descriptive)
### Cluster
**What it is**: Which cluster this lesson belongs to (dropdown)
**Best practices**:
- Create clusters before lessons
- Each lesson belongs to exactly one cluster
- Changing cluster after publishing is okay
### Order
**What it is**: Position within the cluster (number)
**Best practices**:
- Use integers: 1, 2, 3...
- Gaps are okay: 1, 2, 5 works if you might add lessons later
- Lower numbers appear first
### Description
**What it is**: 1-2 sentence summary shown in listings
**Best practices**:
- Answer "What will I learn from this lesson?"
- Be specific, not generic
- Avoid jargon—this is a preview for potential readers
**Examples**:
- ✓ "How Berger and Luckmann explain the process by which human activity becomes objective social reality."
- ✗ "An important reading in sociology." (too vague)
- ✗ "This lesson covers social construction theory including externalization, objectivation, and internalization as described in the 1966 text." (too long for a description)
---
## Core Content Fields
These fields provide the main lesson content.
### Assignment
**What it is**: Instructions for the primary reading
**Structure**:
```yaml
assignment:
instructions: |
What to read and how to approach it.
Markdown formatting works here.
url: "https://archive.org/..."
reading_title: "Full citation of the reading"
```
**Best practices**:
- Include specific page ranges if not reading entire work
- Suggest what to pay attention to
- Estimate time if known ("Approximately 90 minutes")
- Verify the URL works before publishing
### Introduction (Body Content)
**What it is**: Introductory paragraphs shown at top of lesson
**Best practices**:
- 2-4 paragraphs
- Explain why this reading matters
- Connect to the curriculum's central question
- Set up what to expect without summarizing
**What to include**:
- Historical context (when/why was this written?)
- Significance (why is this foundational?)
- Connection (how does this relate to other lessons?)
- Reading guidance (what's the text like to read?)
---
## Content Blocks
Content Blocks are a unified system for all card-like content. Instead of separate fields, you use a single **Content Blocks** list with different block types. Maximum 15 blocks per lesson.
### Learning Objectives Block
**What it is**: Bullet list of what learners will achieve
**Structure**:
```yaml
blocks:
- type: objectives
items:
- "First learning objective"
- "Second learning objective"
```
**Best practices**:
- 3-5 objectives per lesson
- Start with action verbs (Understand, Identify, Apply)
- Be specific about what learners will be able to do
### Key Concept Block
**What it is**: Named concept with detailed explanation
**Structure**:
```yaml
blocks:
- type: concept
name: "Concept Name"
explanation: |
Explanation paragraphs here.
Can include **markdown** formatting.
```
**Best practices**:
- Names should be 2-5 words
- Explanations should be 2-4 paragraphs
- Focus on ideas *in the reading*, not general background
- 3-5 concepts per lesson keeps focus
### Knowledge Check Block
**What it is**: Reflection question for self-assessment
**Structure**:
```yaml
blocks:
- type: check
question: "The question text"
hint: "A hint to guide thinking"
```
**Best practices**:
- Questions should require having done the reading
- Focus on understanding, not recall
- Hints should guide without giving answers
### Resource Block
**What it is**: External resource with link and description
**Structure**:
```yaml
blocks:
- type: resource
title: "Resource Title"
author: "Author Name"
url: "https://..."
description: "Brief description of what this adds"
```
**Best practices**:
- Include a mix of types (articles, videos, related books)
- These are optional—not required for completing the lesson
- Describe what each resource adds
### Callout Blocks
**What it is**: Contextual blocks for tips, examples, warnings, and questions
**Available types**:
- `ask` - "Ask Yourself" - prompts for critical evaluation
- `example` - "Example" - practical illustrations
- `tip` - "Tip" - helpful tips and guidance
- `important` - "Important" - critical notes or warnings
- `reflection` - "Reflection" - reflection questions
- `context` - "Context" - timing or situational guidance
**Structure**:
```yaml
blocks:
- type: important
title: "Custom Title" # optional - overrides default
content: |
Your markdown content here.
Can include **formatting** and multiple paragraphs.
```
**Best practices**:
- Use sparingly throughout the lesson
- Choose the type that best matches your intent
- Custom titles are optional; defaults work well
- Keep content focused and concise
---
## Optional Fields
These enhance lessons but can be added later.
### Reading Author
**What it is**: The author of the primary reading (optional)
**Best practices**:
- Fill in if you want to credit the reading's author
- This appears on the lesson page
- Leave blank if the author is obvious from context
### Featured Image
**What it is**: Image displayed with the lesson (optional)
**Best practices**:
- Use if you have a relevant, high-quality image
- Ensure you have rights to use it
- Leave blank rather than using a generic placeholder
### Hidden Sections
**What it is**: Toggle visibility of sections without deleting content
**Available options**:
- Introduction
- Assignment
- Content Blocks
**Use cases**:
- Test how lessons look with/without certain sections
- Temporarily hide content that's in draft state
- Create cleaner minimal lessons while preserving work-in-progress content
This is a multi-select field—choose any combination of sections to hide.
---
## Field Checklist for New Lessons
When creating a lesson, work through this checklist:
**Required** (lesson won't save without these 5):
- [ ] Title
- [ ] Slug (checked for lowercase, hyphens)
- [ ] Cluster selected
- [ ] Order number
- [ ] Description (1-2 sentences)
**Everything below is optional**—empty sections won't render at all.
**For minimal lessons** (just the reading):
- [ ] Introduction (why this reading matters)
- [ ] Assignment (instructions + reading URL)
**For richer lessons** (add Content Blocks as needed):
- [ ] Learning objectives block (3-5 bullet points)
- [ ] Key concept blocks (3-5 with explanations)
- [ ] Knowledge check blocks (2-4 reflection questions)
- [ ] Resource blocks (2-4 links)
- [ ] Callout blocks (tips, examples, important notes)
- [ ] Reading author (if relevant)
- [ ] Featured image (if available)
---
## Common Mistakes
| Mistake | Problem | Fix |
|---------|---------|-----|
| Changing slugs | Breaks existing links | Never change after publishing |
| Vague descriptions | Learners don't know what they'll get | Be specific about what's learned |
| Too many concept blocks | Dilutes focus | Stick to 3-5 most important |
| Empty body | Lesson feels incomplete | Write at least 2 paragraphs of context |
| Unverified URLs | Learners can't access reading | Always test links before publishing |
| Recall-based questions | Doesn't test understanding | Ask about implications and connections |
| Too many blocks | Overwhelming for learners | Maximum 15 blocks, focus on essentials |
---
### Lesson 3.4: Creating Your First Lesson
Lesson URL: https://byocurriculum.dev/curriculum/building-manually/first-lesson
Description: Walk through creating a complete lesson from scratch—from reading to published content.
## Your First Lesson: A Complete Walkthrough
This lesson guides you through creating one complete lesson, step by step. Use this process for every lesson you create.
## Step 1: Choose and Engage (30-45 minutes)
### Pick Your Reading
For your first lesson, choose:
- A reading you know well
- Something foundational (early in your curriculum)
- A text that clearly connects to your central question
Don't start with the hardest or most obscure reading. Build confidence first.
### Engage With the Text
Even if you've read this before, spend 20-30 minutes re-engaging:
**As you read, note:**
- What are the 3-5 most important ideas?
- What surprised you (or would surprise a newcomer)?
- Where might someone get confused?
- What vocabulary does this text establish?
- How does this connect to other readings in your curriculum?
Write these notes down. They become your lesson content.
## Step 2: Write Your Content (45-60 minutes)
Open your CMS and create the lesson. For each field:
### Title and Basics
| Field | How to Fill It |
|-------|----------------|
| **Title** | The reading's common name or your descriptive title |
| **Slug** | Lowercase, hyphenated version (e.g., `social-construction-reality`) |
| **Cluster** | Select from dropdown |
| **Order** | Position within cluster |
| **Description** | One sentence: what will learners understand after this? |
### Key Concepts
From your notes, select 3-5 concepts. For each:
**Name**: A short phrase identifying the concept
- "The Attention Economy"
- "Institutional Facts"
- "The Medium Is the Message"
**Explanation** (write 2-4 paragraphs):
1. What does this concept mean?
2. Why does it matter for understanding the reading?
3. How will you recognize it in the text?
4. (Optional) How does it connect to other concepts or readings?
Example structure:
```markdown
[Concept name] refers to [definition].
[Author] introduces this idea to explain [purpose].
In the text, you'll see this when [specific example].
This concept matters because [significance].
Understanding it helps you see [broader implication].
```
### Assignment
**Instructions**: Tell learners what to read and how to approach it.
Example:
```markdown
Read chapters 1-2 of *The Social Construction of Reality*
(approximately 60 pages, 90 minutes).
Pay particular attention to the three-step process of
externalization, objectivation, and internalization.
Mark passages where the authors give concrete examples—
these illustrate abstract concepts.
If the philosophical language feels dense, slow down.
This isn't meant to be skimmed.
```
**URL**: Link to where learners can access the reading
- Check Internet Archive first
- Verify the link works
**Reading Title**: Full citation
- "Berger, P. & Luckmann, T. (1966). *The Social Construction of Reality*. Anchor Books."
### Body Content
Write 2-4 paragraphs introducing the lesson. Structure:
**Paragraph 1: Why this matters**
```markdown
Published in 1966, *The Social Construction of Reality*
fundamentally changed how sociologists think about knowledge.
Its central insight—that "reality" is something humans
create together—underpins everything else in this curriculum.
```
**Paragraph 2: Context**
```markdown
Berger and Luckmann were responding to a problem: how do
shared beliefs become so solid they feel like facts?
Their answer draws on phenomenology (Schutz) and
sociology of knowledge (Mannheim) to explain the process.
```
**Paragraph 3: What to expect**
```markdown
The text is theoretical and sometimes dense, but the
examples are clarifying. The authors use everyday
situations—how children learn "the way things are,"
how institutions outlive their creators—to illustrate
abstract points.
```
### Knowledge Check
Write 2-4 questions. Good questions:
- Require having done the reading
- Test understanding, not recall
- Connect to curriculum themes
Example:
```markdown
Question: "How does 'objectivation' make human-created
patterns feel like external facts?"
Hint: "Think about what happens when 'this is how we
do it' becomes 'this is how it's done.'"
```
### Additional Resources
Add 2-4 links for learners who want more:
- Related readings
- Video explanations
- Background material
- Applications of the ideas
For each, write a brief description of what it adds.
## Step 3: Review and Publish (15 minutes)
### Self-Review Checklist
Before publishing, verify:
- [ ] All required fields are filled
- [ ] Reading link works
- [ ] No obvious typos in visible content
- [ ] Key concepts are actually in the reading
- [ ] Description accurately reflects the lesson
### Preview
1. Save the lesson in the CMS
2. Wait 1-2 minutes for deployment
3. Visit your site and navigate to the lesson
4. Read through the page as a learner would
5. Click the assignment link to verify access
### Publish
If everything looks acceptable, you're done. The lesson is live.
Acceptable means "good enough to learn from," not "perfect." You can improve it later.
## Step 4: Repeat
You've now created one complete lesson. The process for lesson #2 is identical:
1. Choose a reading
2. Engage with it (notes on concepts, confusions, connections)
3. Fill in CMS fields
4. Review and publish
Each lesson gets easier. By lesson #5, this will feel routine.
## Common First-Lesson Mistakes
| Mistake | Problem | Fix |
|---------|---------|-----|
| Summarizing the reading | Removes reason to read it | Focus on setup and guidance, not summary |
| Too many key concepts | Overwhelming, dilutes focus | Stick to 3-5 most important |
| Generic body content | Doesn't motivate the reading | Be specific about why *this* text matters |
| Untested links | Learners can't access reading | Always click the link before publishing |
| Waiting for perfection | Curriculum never launches | Publish "good enough," improve later |
## After Your First Lesson
Congratulations—you have a live curriculum with real content.
Now:
1. Create the rest of your first cluster's lessons
2. Move to the second cluster
3. Continue until your curriculum is complete
Each lesson teaches you something about your own curriculum design process. Trust the iteration.
---
## Cluster 4: Deployment & Customization (Foundation)
Cluster URL: https://byocurriculum.dev/curriculum/deployment-customization
Description: Setting up your site, connecting the CMS, and making it your own.
Once you've designed your curriculum, it's time to deploy it and make it accessible to your audience.
This cluster covers the technical setup: deploying to Netlify, configuring the CMS authentication, customizing the look and feel, and ongoing maintenance. Everything is designed to be done without writing code.
### Lesson 4.1: Deploying to Netlify
Lesson URL: https://byocurriculum.dev/curriculum/deployment-customization/deploying-netlify
Description: Fork the repository, connect to Netlify, and get your curriculum online in minutes.
## Before You Begin
**This is the most important lesson in this cluster.** Complete it before moving to any other deployment lessons. You cannot set up the CMS or customize your site until your curriculum is deployed.
**Time required**: About 15 minutes
**What you'll accomplish**:
- Create accounts on GitHub and Netlify (both free)
- Get your own copy of the curriculum template
- Deploy it to a live URL you can share
- Verify everything works
---
## Step 1: Create a GitHub Account
GitHub stores your curriculum files and tracks all changes. Think of it as a smart folder in the cloud that remembers every version of every file.
**If you don't have an account:**
1. Go to [github.com/signup](https://github.com/signup)
2. Enter your email address
3. Create a password
4. Choose a username
- This will appear in your URLs, so pick something professional
- Example: `jsmith` gives you URLs like `github.com/jsmith/...`
5. Complete the verification puzzle
6. Choose the **Free** plan when asked (it has everything you need)
**If you already have a GitHub account:** Make sure you're logged in at [github.com](https://github.com).
---
## Step 2: Fork the Curriculum Template
"Forking" creates your own copy of the template that you can customize.
### Find the Template
Go to the curriculum template repository:
[**`https://github.com/K41R0N/opensource-curriculum`**](https://github.com/K41R0N/opensource-curriculum)
> **Note**: Replace the URL above with the actual template repository URL provided to you. If you're reading this on a deployed curriculum, the template owner should have this information in their documentation.
### Create Your Fork
1. Click the **Fork** button in the top-right corner of the page
2. On the "Create a new fork" page:
- **Owner**: Select your GitHub account
- **Repository name**: Give it a descriptive name (e.g., `philosophy-curriculum`, `design-reading-list`, `my-curriculum`)
- **Description**: Optional, but helpful (e.g., "My self-directed curriculum on...")
3. Leave "Copy the main branch only" checked
4. Click **Create fork**
**Wait for it to complete.** You'll be redirected to your new repository at `github.com/YOUR-USERNAME/your-repo-name`.
> **Congratulations!** You now have your own curriculum repository. Everything from here on happens in YOUR copy, not the original template.
---
## Step 3: Create a Netlify Account
Netlify will host your site and make it available on the internet.
1. Go to [app.netlify.com/signup](https://app.netlify.com/signup)
2. Click **Sign up with GitHub** (this is the easiest option)
3. Authorize Netlify to access your GitHub account when prompted
4. You'll land on the Netlify dashboard
> **Why sign up with GitHub?** It automatically links your accounts, making the next step easier. You could also sign up with email, but you'd need to link GitHub anyway.
---
## Step 4: Deploy Your Site
Now we'll connect your GitHub repository to Netlify.
### Connect Your Repository
1. On the Netlify dashboard, click **Add new site**
2. Select **Import an existing project**
3. Click **Deploy with GitHub**
4. You may be asked to authorize Netlify again—click **Authorize**
5. **Find your repository** in the list
- If you don't see it, click "Configure the Netlify app on GitHub" and grant access to your repository
6. Click on your curriculum repository to select it
### Configure Build Settings
Netlify will show you build configuration options:
| Setting | Value | Notes |
| --- | --- | --- |
| Branch to deploy | `main` | Leave as default |
| Build command | `npm run build` | Should be pre-filled |
| Publish directory | `build` | Should be pre-filled |
**These should already be correct!** The template includes a `netlify.toml` file that configures everything.
7. Click **Deploy site**
### Wait for the Build
Netlify will now:
1. Download your repository
2. Install dependencies
3. Build your site
4. Deploy it to their servers
This takes **1-3 minutes**. You'll see a progress log. When it says "Published," your site is live!
---
## Step 5: Get Your Site URL
After deployment, Netlify assigns a random URL like `silly-einstein-a1b2c3.netlify.app`.
### Find Your URL
1. Look at the top of your Netlify site dashboard
2. You'll see your URL displayed prominently
3. Click it to visit your live site!
### Customize Your URL (Optional but Recommended)
That random URL works, but you probably want something nicer:
1. Go to **Site configuration** (or "Site settings" on older interface)
2. Click **Change site name** (or find it under "Domain management")
3. Enter your preferred name (e.g., `my-philosophy-curriculum`)
4. Click **Save**
Your site is now at `my-philosophy-curriculum.netlify.app` (or whatever you chose).
> **Tip**: Choose a name that's short, memorable, and describes your curriculum.
---
## Step 6: Set the Environment Variable
One last configuration step ensures your site works correctly:
1. In Netlify, go to **Site configuration** → **Environment variables**
2. Click **Add a variable**
3. Fill in:
- **Key**: `PUBLIC_SITE_URL`
- **Value**: Your full site URL (e.g., `https://my-philosophy-curriculum.netlify.app`)
4. Click **Create variable**
### Trigger a Redeploy
For the variable to take effect:
1. Go to **Deploys** in the sidebar
2. Click **Trigger deploy** → **Deploy site**
3. Wait for the build to complete (1-2 minutes)
---
## Step 7: Verify Your Site Works
Visit your site and check that everything loads:
- [ ] Homepage displays with your site title
- [ ] "Explore the Curriculum" button works
- [ ] Curriculum page shows clusters and lessons
- [ ] At least one lesson opens and displays content
- [ ] About page loads
**If something doesn't look right**, see the Troubleshooting section below.
---
## How Updates Work
From now on, your site updates automatically whenever you change content:
| Action | What Happens |
| --- | --- |
| Edit in CMS | CMS commits to GitHub → Netlify rebuilds → Live in 1-2 min |
| Edit with Obsidian | You push to GitHub → Netlify rebuilds → Live in 1-2 min |
| Edit on GitHub directly | Save triggers → Netlify rebuilds → Live in 1-2 min |
You never need to manually deploy again. Just edit content, and it goes live.
---
## Troubleshooting
### Build Failed
If Netlify shows "Build failed":
1. Click on the failed deploy to see the log
2. Scroll to find the error message (usually in red)
3. Common causes:
- **Missing dependencies**: Try clicking "Retry deploy"
- **Content validation error**: Check your content files for missing required fields
- **Syntax error in content**: Look for malformed YAML in frontmatter
### Site Shows Old Content
1. Go to Netlify **Deploys**
2. Check if the latest deploy succeeded
3. If stuck, click **Trigger deploy** → **Clear cache and deploy site**
### Can't Find My Repository
When connecting GitHub to Netlify:
1. Click "Configure the Netlify app on GitHub"
2. Under "Repository access," select "All repositories" or specifically add yours
3. Save and return to Netlify
### Site URL Not Working
- Make sure you're using `https://` not `http://`
- Wait a few minutes—DNS can take time to propagate
- Check that the deploy completed successfully
---
## Custom Domain (Optional)
Want to use your own domain like `curriculum.yoursite.com`?
1. Go to **Site configuration** → **Domain management**
2. Click **Add a domain**
3. Enter your domain name
4. Follow Netlify's instructions to update your DNS settings
5. Wait for DNS propagation (can take up to 48 hours, usually much faster)
6. Netlify automatically handles SSL certificates
The free `.netlify.app` domain works perfectly well if you don't have a custom domain.
---
## What's Next?
Your site is deployed! In the next lesson, you'll set up the CMS so you can edit content through a friendly web interface instead of editing files directly.
---
### Lesson 4.2: Setting Up the CMS
Lesson URL: https://byocurriculum.dev/curriculum/deployment-customization/cms-setup
Description: Configure authentication so you can edit content through the browser-based CMS.
## Before You Begin
**This is the most technical lesson in the curriculum.** Don't worry—you won't need to write any code. You'll just be copying and pasting values between websites. But it does require careful attention to detail.
**Time required**: 20-30 minutes
**What you'll set up**:
- A way for the CMS to securely verify you're the owner
- The ability to edit content through a friendly web interface
**Tip**: Open a text file or notes app to temporarily store values as you go. You'll copy several codes and URLs that need to be pasted elsewhere.
---
## Overview: What We're Building
```text
You CMS GitHub
│ │ │
├── Click "Login" ─────────→│ │
│ ├── Redirect to GitHub ─────→│
│ │ │
│←──────────────────────────┼── "Allow access?" ←────────┤
│ │ │
├── Click "Authorize" ─────→│ │
│ │ │
│ Cloudflare Worker │
│ │ │
│ ├── Verify & get token ─────→│
│ │ │
│←── Now logged in ─────────┤ │
```
The Cloudflare Worker is a tiny helper (free) that handles the security handshake between the CMS and GitHub. Let's set it all up.
---
## Step 1: Create a Cloudflare Account
Cloudflare provides the helper service that handles login. It's free.
1. Go to [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)
2. Enter your email and create a password
3. Verify your email if prompted
4. You'll land on the Cloudflare dashboard
> **Note**: If you already have a Cloudflare account, just log in.
---
## Step 2: Create the Worker
A "Worker" is a small program that runs on Cloudflare's servers. We need one to handle the login process.
### Create a New Worker
1. In the Cloudflare dashboard sidebar, click **Workers & Pages**
2. Click **Create**
3. Select **Create Worker**
4. Give it a name: `curriculum-auth` (or any name you'll remember)
5. Click **Deploy** (we'll edit the code next)
### Edit the Worker Code
1. After deploying, click **Edit code** (or go to your worker and click "Quick edit")
2. **Delete all the existing code** in the editor
3. **Copy the entire code block below** and paste it:
```javascript
export default {
async fetch(request, env) {
const url = new URL(request.url);
// Step 1: Start the login - redirect to GitHub
if (url.pathname === '/auth') {
const authUrl = new URL('https://github.com/login/oauth/authorize');
authUrl.searchParams.set('client_id', env.GITHUB_CLIENT_ID);
authUrl.searchParams.set('redirect_uri', `${url.origin}/callback`);
authUrl.searchParams.set('scope', 'repo user');
authUrl.searchParams.set('state', crypto.randomUUID());
return Response.redirect(authUrl.toString(), 302);
}
// Step 2: Handle GitHub's response
if (url.pathname === '/callback') {
const code = url.searchParams.get('code');
// Exchange the code for an access token
const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({
client_id: env.GITHUB_CLIENT_ID,
client_secret: env.GITHUB_CLIENT_SECRET,
code: code
})
});
const tokenData = await tokenResponse.json();
// Send the token back to the CMS
const script = `
`;
return new Response(script, {
headers: { 'Content-Type': 'text/html' }
});
}
return new Response('OAuth Worker - visit /auth to begin', { status: 200 });
}
};
```
4. Click **Save and Deploy**
### Get Your Worker URL
After deploying, you'll see your worker URL. It looks like:
```text
https://curriculum-auth.YOUR-USERNAME.workers.dev
```
**Write this URL down!** You'll need it in the next steps.
---
## Step 3: Create a GitHub OAuth App
Now we need to tell GitHub about your CMS.
### Navigate to OAuth Apps
1. Go to [github.com](https://github.com) and log in
2. Click your **profile picture** (top right) → **Settings**
3. Scroll down the left sidebar and click **Developer settings**
4. Click **OAuth Apps** → **New OAuth App**
### Fill In the Form
| Field | What to Enter |
|-------|---------------|
| **Application name** | `My Curriculum CMS` (or any name) |
| **Homepage URL** | Your Netlify site URL (e.g., `https://my-curriculum.netlify.app`) |
| **Application description** | Optional — you can leave this blank |
| **Authorization callback URL** | Your worker URL + `/callback` (e.g., `https://curriculum-auth.yourname.workers.dev/callback`) |
5. Click **Register application**
### Copy Your Credentials
After registering, you'll see your app's settings page.
1. **Copy the Client ID** — Save it to your notes
2. Click **Generate a new client secret**
3. **Copy the Client Secret immediately** — You won't be able to see it again!
> **Important**: Keep these safe! The Client Secret is like a password. Don't share it publicly.
---
## Step 4: Configure the Worker Variables
Go back to Cloudflare and add your GitHub credentials to the worker.
1. Go to **Workers & Pages** → click on your worker
2. Click the **Settings** tab
3. Click **Variables and Secrets** (under "Bindings" section)
4. Click **Add** for each variable:
| Variable Name | Value | Type |
|---------------|-------|------|
| `GITHUB_CLIENT_ID` | Your GitHub Client ID | Text |
| `GITHUB_CLIENT_SECRET` | Your GitHub Client Secret | Secret (click "Encrypt") |
5. Click **Deploy** to save the changes
---
## Step 5: Add Netlify Environment Variables
Now tell your Netlify site where to find everything.
1. Go to your site in the **Netlify dashboard**
2. Click **Site settings** → **Environment variables**
3. Add these two variables:
| Variable Name | Value |
|---------------|-------|
| `CMS_REPO` | Your GitHub username/repo (e.g., `myname/my-curriculum`) |
| `CMS_AUTH_URL` | Your Cloudflare Worker URL (e.g., `https://curriculum-auth.yourname.workers.dev`) |
4. Go to **Deploys** → Click **Trigger deploy** → **Deploy site**
Wait 1-2 minutes for Netlify to rebuild your site with the new configuration.
---
## Step 6: Test the Login
The moment of truth!
1. Go to your site's admin page: `https://your-site.netlify.app/admin/`
2. Click **Login with GitHub**
3. GitHub will ask if you want to authorize your app — click **Authorize**
4. You should be redirected back to the CMS dashboard
**If you see the CMS dashboard with your content listed: Success!**
---
## Troubleshooting
### "Failed to fetch" or blank screen after clicking login
**Likely cause**: Environment variables not set correctly, or site not redeployed.
**Fix**:
1. Check that `CMS_AUTH_URL` is set in Netlify environment variables
2. Make sure you triggered a redeploy after adding the variables
3. Visit your worker URL directly (e.g., `https://curriculum-auth.yourname.workers.dev`)
4. You should see "OAuth Worker - visit /auth to begin"
### "Bad credentials" error
**Likely cause**: Client ID or Secret is wrong.
**Fix**:
1. Double-check the values in Cloudflare match exactly what's in GitHub
2. Make sure you didn't accidentally add spaces when copying
3. Try regenerating a new client secret in GitHub and updating Cloudflare
### Login popup closes but nothing happens
**Likely cause**: Callback URL mismatch.
**Fix**:
1. In GitHub OAuth App settings, check the "Authorization callback URL"
2. It should be your worker URL + `/callback`
3. These must match **exactly** (including `https://`)
### "Not found" or 404 errors
**Likely cause**: Worker code isn't right.
**Fix**:
1. Go to your worker in Cloudflare and click "Quick edit"
2. Make sure the code is exactly as shown above
3. Click "Save and Deploy" again
### Can see CMS but changes won't save
**Likely cause**: Repository name is wrong, or you don't have write access.
**Fix**:
1. Check `CMS_REPO` in Netlify matches your exact username and repo name
2. Make sure you're logged into the GitHub account that owns the repository
---
## Success!
Once you can log in and see the CMS dashboard, you're ready to start editing content through the browser. The next lesson covers basic customization options.
**What you can now do**:
- Edit lessons, clusters, and pages through a visual interface
- Save changes that automatically publish to your live site
- Add images and manage content without touching code
The CMS is accessed at `your-site.netlify.app/admin/` whenever you need to edit.
---
### Lesson 4.3: Customizing Your Curriculum
Lesson URL: https://byocurriculum.dev/curriculum/deployment-customization/customization
Description: Brand your curriculum with custom colors, logos, and site settings—no code required.
## Making It Yours
Your curriculum is deployed and the CMS works. Now it's time to make it feel like yours.
## Priority Order
Resist the temptation to start with colors and logos. The most impactful customizations are:
1. **Content** - What you teach matters most
2. **Messaging** - Clear descriptions of what learners gain
3. **Visual identity** - Colors, logos, typography
Work in this order for maximum impact with minimum effort.
## Site Settings
The CMS provides a simple interface for core settings:
1. Navigate to `/admin/`
2. Click "Settings" in the sidebar
3. Select "Site Settings"
Here you can update:
- **Site Title**: Appears in browser tabs and search results
- **Description**: The meta description for SEO
- **Author**: Attribution shown in the footer
Changes save to `content/settings/site.json` and trigger a rebuild.
## The About Page
Your About page is often the second page visitors read. Make it count.
Good About pages include:
- **The problem**: What gap does this curriculum fill?
- **The approach**: How is this different from alternatives?
- **The outcome**: What will learners be able to do?
- **Your credibility**: Why should they trust this curriculum?
Edit it through the CMS under "Pages" → "About".
## Color Theming
The curriculum uses CSS custom properties for easy theming. To change colors:
1. Open `src/app.css` in your code editor
2. Find the `:root` block (near the top)
3. Modify the color variables:
```css
:root {
/* Primary color - used for links, buttons, accents */
--color-primary: #2563eb;
/* Background colors */
--color-background: #ffffff;
--color-surface: #f9fafb;
/* Text colors */
--color-text: #1f2937;
--color-text-muted: #6b7280;
/* Other colors */
--color-border: #e5e7eb;
--color-success: #10b981;
}
```
### Choosing Colors
For academic curricula, consider:
- **Muted, professional tones** - Blues, greens, warm grays
- **High contrast** - Ensure text is readable
- **Consistency** - One primary color, used consistently
Tools for color selection:
- [Coolors](https://coolors.co) - Palette generator
- [Contrast Checker](https://webaim.org/resources/contrastchecker/) - Accessibility verification
### Dark Mode
The template includes basic dark mode support via `prefers-color-scheme`. To customize dark mode colors, add:
```css
@media (prefers-color-scheme: dark) {
:root {
--color-background: #1f2937;
--color-surface: #374151;
--color-text: #f9fafb;
/* ... other dark mode colors */
}
}
```
## Typography
To change fonts:
1. Add your font (Google Fonts, local files, etc.)
2. Update the font variables:
```css
:root {
--font-body: 'Inter', system-ui, sans-serif;
--font-heading: 'Playfair Display', Georgia, serif;
--font-mono: 'JetBrains Mono', monospace;
}
```
For academic content, consider:
- **Serif headings** - Traditional, scholarly feel
- **Sans-serif body** - Clean, readable on screens
- **Generous line height** - 1.5-1.7 for body text
## Adding a Logo
To add a logo:
1. Create or obtain your logo (SVG preferred for quality)
2. Save it to `static/images/logo.svg`
3. The header component will display it
For text-only branding, the site title displays in the header by default.
## Favicon
To change the browser tab icon:
1. Create a favicon (use [favicon.io](https://favicon.io) for generation)
2. Replace `static/favicon.png`
3. Redeploy
## Advanced Customization
For deeper changes, you can edit the Svelte components directly:
- `src/routes/+layout.svelte` - Site-wide layout
- `src/routes/+page.svelte` - Homepage
- Component styling in each `.svelte` file
This requires basic knowledge of HTML, CSS, and Svelte. The codebase is intentionally simple to make customization accessible.
## What Not to Customize
Some things are better left alone:
- **Content structure** - The cluster/lesson hierarchy works
- **CMS configuration** - Unless you understand the implications
- **Build settings** - The defaults are optimized
Focus your energy on content and light visual tweaks. The infrastructure should fade into the background.
---
## Cluster 5: Working With Your Content
Cluster URL: https://byocurriculum.dev/curriculum/working-with-content
Description: Day-to-day content management, editing workflows, and iterating on your curriculum.
Your curriculum is live—now what? This cluster covers the ongoing work of maintaining and improving your content.
You'll learn how to use the web-based CMS for quick edits, set up local editing with Obsidian for deeper work sessions, and develop a practice of iteration that keeps your curriculum growing and improving over time.
### Lesson 5.1: Using the CMS
Lesson URL: https://byocurriculum.dev/curriculum/working-with-content/using-cms
Description: Add and edit content through the browser-based CMS without touching code.
## Accessing the CMS
Once you've completed the OAuth setup (covered in the Deployment cluster), you can access the CMS at:
```text
https://your-site.netlify.app/admin/
```
You'll be prompted to log in with GitHub. After authenticating, you'll see the CMS dashboard.
## The CMS Interface
The interface has three main areas:
1. **Sidebar**: Lists your content collections (Clusters, Lessons, Pages, Settings)
2. **Content List**: Shows all items in the selected collection
3. **Editor**: The form where you edit content
## Creating a New Lesson
Let's walk through creating a new lesson:
### Step 1: Select the Lessons Collection
Click "Lessons" in the sidebar. You'll see a list of all existing lessons.
### Step 2: Click "New Lesson"
This opens a blank editor with fields for:
- **Title**: The lesson name
- **Slug**: URL identifier (auto-generated from title, but editable)
- **Cluster**: Dropdown to select which cluster this belongs to
- **Order**: Position within the cluster
- **Description**: Brief summary for previews
- And more fields for objectives, concepts, assignments, etc.
### Step 3: Fill In Required Fields
At minimum, every lesson needs:
| Field | Example |
|-------|---------|
| Title | "Understanding Markdown" |
| Slug | `understanding-markdown` |
| Cluster | Select from dropdown |
| Order | `3` (unique within the cluster) |
| Description | "Learn the basics of Markdown formatting." |
### Step 4: Add Content
The main body editor supports Markdown with a visual preview. You can:
- Use the toolbar for formatting (bold, italic, links)
- Switch between "Rich Text" and "Markdown" modes
- Preview how it will look on the site
### Step 5: Publish
Click the "Publish" button. The CMS will:
1. Create a commit with your new lesson
2. Push it to your GitHub repository
3. Trigger a Netlify rebuild
Your new lesson will be live in 1-2 minutes.
## Editing Existing Content
To edit existing content:
1. Click on any item in the content list
2. Make your changes in the editor
3. Click "Publish" to save
Each edit creates a new commit, so you can always see (and revert) the history in GitHub.
## Creating Clusters
Creating a cluster follows the same pattern:
1. Select "Clusters" in the sidebar
2. Click "New Cluster"
3. Fill in Title, Slug, Order, Description
4. Add optional body text
5. Publish
**Important**: Create the cluster *before* creating lessons that belong to it. The Lesson editor's Cluster dropdown only shows existing clusters.
## Tips for Effective CMS Use
### Use Descriptive Slugs
Slugs become URLs. Instead of auto-generated slugs like `lesson-1`, use meaningful ones like `introduction-to-rhetoric`.
### Keep Order Numbers Sequential
Within each cluster, use sequential order numbers (1, 2, 3...). Gaps are fine, but avoid duplicates—the build will fail.
### Preview Before Publishing
The CMS shows a preview, but you can also:
1. Publish to a draft branch (if configured)
2. Check the Netlify deploy preview
3. Review on your live site after publishing
### Use the Rich Text Editor for Complex Formatting
For lists, links, and basic formatting, the Rich Text mode is easier. Switch to Markdown mode when you need:
- Code blocks
- Complex nested structures
- Direct control over formatting
## What If Something Goes Wrong?
### Build Fails After Publishing
Check Netlify's deploy logs. Common causes:
- Duplicate order numbers
- Missing required fields
- Cluster reference that doesn't exist
### Need to Revert a Change?
Every CMS edit is a git commit. In GitHub:
1. Go to your repository
2. Click "Commits"
3. Find the commit to revert
4. Use "Revert" to undo it
### CMS Won't Load?
- Check that OAuth is properly configured
- Try logging out and back in
- Clear browser cache
## Next Steps
The CMS is great for quick edits and creating new content. For longer writing sessions or working offline, you might prefer local editing with Obsidian—covered in the next lesson.
---
### Lesson 5.2: Local Editing with Obsidian
Lesson URL: https://byocurriculum.dev/curriculum/working-with-content/local-editing
Description: Set up a powerful local editing environment for longer writing sessions and offline work.
## When to Use Local Editing
The CMS and local editing aren't competing—they're complementary tools for different situations.
**Use the CMS when:**
- Making a quick fix (typo, broken link)
- You're away from your main computer
- You want changes live immediately
- You're less comfortable with Git
**Use local editing when:**
- Writing a new lesson from scratch
- Doing a major revision
- Working without internet
- You want Obsidian's power features
Many authors keep both options available and switch based on the task.
---
## Complete Setup Guide
This setup has 6 parts. Follow them in order—each step builds on the previous one.
**Time required**: About 30 minutes for first-time setup.
### Part 1: Install Git
Git is the tool that syncs your changes between your computer and GitHub.
#### On Mac
1. Open **Terminal** (press Cmd + Space, type "Terminal", press Enter)
2. Type this command and press Enter:
```bash
git --version
```
3. If Git isn't installed, a popup will appear asking to install developer tools
4. Click **Install** and wait for it to complete (this may take a few minutes)
5. Run `git --version` again to confirm—you should see something like `git version 2.39.0`
#### On Windows
1. Go to [git-scm.com/download/win](https://git-scm.com/download/win)
2. The download should start automatically
3. Run the installer
4. **Important**: Accept all the default options—just keep clicking "Next"
5. Click "Install" and wait for completion
6. Open **Command Prompt** (press Windows key, type "cmd", press Enter)
7. Type `git --version` and press Enter to confirm installation
> **Troubleshooting**: If you see "command not found," restart your computer and try again. The installer sometimes needs a restart to complete.
### Part 2: Configure Git with Your Identity
Git needs to know who you are (for tracking who made each change).
Open Terminal (Mac) or Command Prompt (Windows) and run these two commands, replacing the placeholder text with your actual information:
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```
**Use the same email as your GitHub account.** This connects your local work to your GitHub identity.
### Part 3: Clone Your Repository
"Cloning" downloads your curriculum files to your computer.
#### Step 1: Get Your Repository URL
1. Go to your curriculum repository on GitHub
2. Click the green **Code** button
3. Make sure **HTTPS** is selected (not SSH)
4. Click the copy button (📋) next to the URL
The URL looks like: `https://github.com/yourusername/your-curriculum.git`
#### Step 2: Choose Where to Store It
Pick a location on your computer. We recommend your Documents folder:
- **Mac**: `/Users/yourname/Documents/`
- **Windows**: `C:\Users\yourname\Documents\`
#### Step 3: Clone
Open Terminal (Mac) or Command Prompt (Windows):
```bash
# Navigate to your Documents folder
cd ~/Documents
# Clone your repository (paste your URL)
git clone https://github.com/yourusername/your-curriculum.git
```
**Replace** `yourusername/your-curriculum` with your actual repository path.
You'll see output showing files being downloaded. When it finishes, you have a complete copy of your curriculum on your computer.
### Part 4: Set Up Obsidian
#### Step 1: Download and Install Obsidian
1. Go to [obsidian.md/download](https://obsidian.md/download)
2. Download the version for your operating system
3. Install it (drag to Applications on Mac, or run the installer on Windows)
4. Open Obsidian
#### Step 2: Open Your Content as a Vault
1. In Obsidian, click **Open folder as vault**
2. Navigate to where you cloned your repository
3. Select the **content** folder inside your repository (not the root folder)
- Example path: `Documents/your-curriculum/content`
4. Click **Open**
> **Why the content folder?** This keeps Obsidian focused on your actual content files, not the code files you don't need to edit.
#### Step 3: Trust the Folder
Obsidian may ask if you trust this folder. Click **Trust author and enable plugins**.
You should now see your curriculum structure:
```
clusters/ ← Your thematic groupings
lessons/ ← Individual lessons
pages/ ← Home and About pages
settings/ ← Site configuration
```
### Part 5: Install the Obsidian Git Plugin
This plugin lets you sync changes without leaving Obsidian.
1. In Obsidian, click the gear icon (⚙️) in the bottom-left to open Settings
2. Go to **Community plugins** in the left sidebar
3. Click **Turn on community plugins** if prompted, then confirm
4. Click **Browse**
5. Search for **"Obsidian Git"**
6. Click on **Obsidian Git** by Vinzent
7. Click **Install**
8. Click **Enable**
#### Configure the Plugin
1. Still in Settings, scroll down to **Obsidian Git** in the left sidebar
2. Recommended settings:
| Setting | Value | Why |
|---------|-------|-----|
| Auto backup interval | `10` | Saves changes every 10 minutes |
| Auto pull interval | `10` | Checks for remote changes |
| Commit message | `Update content` | Default message for auto-commits |
| Push on backup | ✅ On | Automatically pushes when backing up |
### Part 6: Authenticate with GitHub
The first time you try to push, Git needs to verify you have permission.
#### Create a Personal Access Token
1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
2. Click **Generate new token (classic)**
3. Give it a name: "Obsidian Curriculum" (or anything descriptive)
4. Under **Expiration**, choose "No expiration" (or set a reminder to renew)
5. Under **Select scopes**, check **repo** (this grants access to your repositories)
6. Click **Generate token**
7. **Copy the token immediately**—you won't be able to see it again
> **Keep this token safe!** It's like a password. Store it in a password manager or secure note.
#### Test the Connection
Let's verify everything works:
1. In Obsidian, open any file (try `pages/about.md`)
2. Make a small change (add a word, fix a typo)
3. Open the command palette: **Cmd+P** (Mac) or **Ctrl+P** (Windows)
4. Type "Git" to see available commands
5. Select **Obsidian Git: Commit all changes**
6. Select **Obsidian Git: Push**
The first time you push, you'll be prompted for credentials:
- **Username**: Your GitHub username
- **Password**: Paste your Personal Access Token (not your GitHub password)
If successful, check your GitHub repository—you should see your commit!
---
## Your Daily Workflow
Once setup is complete, your daily workflow is simple:
### Starting a Session
1. Open Obsidian
2. Run "Obsidian Git: Pull" (Cmd/Ctrl + P, type "pull")
3. Start editing
The pull step ensures you have the latest changes—important if you sometimes edit via CMS or from another device.
### While Editing
- Files auto-save in Obsidian
- Make as many changes as you want
- Use graph view to see connections
- Use quick switcher (Cmd/Ctrl + O) to jump between files
### Ending a Session
1. Run "Obsidian Git: Commit all changes"
2. Run "Obsidian Git: Push"
Or, if you've enabled auto-backup, just close Obsidian—changes sync automatically.
## Obsidian Features for Curriculum Authors
### Graph View
The graph view (View → Graph view) shows your content as a network of connected nodes. For a curriculum, this reveals:
- Which clusters have the most lessons
- How content is interconnected
- Orphaned files that might need attention
### Quick Switcher
Press Cmd/Ctrl + O to instantly jump to any file by name. This is faster than navigating folders when you're editing multiple lessons.
### Templates
Create a template for new lessons:
1. Create a `templates/` folder in your vault
2. Add a file like `lesson-template.md` with your standard frontmatter
3. Use the Templates core plugin or Templater community plugin to insert it
Example template:
```markdown
---
title: ""
slug: ""
cluster:
order:
description: ""
objectives:
- ""
key_concepts:
- name: ""
explanation: |
---
## Introduction
```
### Search
Use Cmd/Ctrl + Shift + F to search across all files. Useful for:
- Finding all mentions of a concept
- Checking consistency across lessons
- Locating content to link to
## Handling Conflicts
If you edit the same file in two places (say, CMS and local), you'll get a merge conflict when you pull. Here's how to resolve it:
1. Obsidian Git will warn you about the conflict
2. Open the conflicting file
3. Look for markers like `<<<<<<<` and `>>>>>>>`
4. Edit the file to keep the content you want
5. Remove the conflict markers
6. Commit and push
To avoid conflicts:
- Always pull before starting a session
- Don't edit the same file in two places simultaneously
- Use CMS for quick edits, local for deep work (not both at once)
## Tips for Productive Local Editing
### Use Split View
Open the lesson you're writing alongside related content. Obsidian lets you split the view horizontally or vertically.
### Enable Live Preview
In Settings → Editor, enable "Live Preview" mode. You'll see formatted Markdown as you type, while still having full control over the source.
### Create a Writing Ritual
Local editing works best with dedicated time. Set aside blocks for curriculum work:
- Morning: Review and edit existing lessons
- Afternoon: Draft new content
- Weekly: Review the graph, look for gaps
### Back Up Your Work
Git is your backup, but commits only save when you push. Get in the habit of:
- Pushing at least daily
- Enabling auto-backup in Obsidian Git settings
- Occasionally verifying changes appear on GitHub
---
## Troubleshooting Common Issues
### "Authentication failed" when pushing
**Cause**: Your GitHub credentials are missing or expired.
**Solution**:
1. Generate a new [Personal Access Token](https://github.com/settings/tokens)
2. On Mac: Open "Keychain Access" app, search for "github", delete old entries
3. On Windows: Open "Credential Manager" (search in Start menu), find GitHub entries, remove them
4. Try pushing again—you'll be prompted for new credentials
### "Repository not found" error
**Cause**: The repository URL is wrong, or you don't have access.
**Solution**:
1. Check the URL matches your actual repository
2. Make sure you forked the template (not just cloned it)
3. Verify you're logged into the correct GitHub account
### "Merge conflict" when pulling
**Cause**: You edited the same file in two places (like CMS and locally).
**Solution**:
1. Open the conflicting file in Obsidian
2. Look for lines starting with `<<<<<<<`, `=======`, and `>>>>>>>`
3. These show both versions—choose which content to keep
4. Delete the conflict markers entirely
5. Save, commit, and push
**Prevention**: Always pull before starting a session.
### Obsidian Git commands not appearing
**Cause**: Plugin isn't enabled or installed.
**Solution**:
1. Go to Settings → Community plugins
2. Make sure community plugins are turned on
3. Check that "Obsidian Git" is both installed AND enabled
4. Try restarting Obsidian
### Changes not appearing on live site
**Cause**: Changes weren't pushed, or the build failed.
**Solution**:
1. In Obsidian, run "Obsidian Git: Push" manually
2. Go to your GitHub repository and check if your commit appears
3. If the commit is there, check Netlify's deploy logs for build errors
4. Common build errors: missing required fields, duplicate order numbers
---
## Next Steps
Now you can edit content both through the CMS and locally. The next lesson covers the ongoing practice of iteration—how to improve your curriculum over time based on feedback and your own evolving understanding.
---
### Lesson 5.3: Iterating on Your Curriculum
Lesson URL: https://byocurriculum.dev/curriculum/working-with-content/iterating
Description: Develop a practice of continuous improvement based on feedback and deeper understanding.
## The Case for Iteration
The first version of any curriculum is a hypothesis: "I think these readings, in this order, with this framing, will produce genuine understanding."
You can't know if the hypothesis is correct until people use it—including yourself. Iteration is how you refine the hypothesis based on evidence.
The goal isn't perfection. It's *better*—continuously, sustainably better.
## Establishing a Review Cadence
### Monthly: Quick Check
Once a month, spend 30 minutes:
- Skim through recent lessons you've written
- Note anything that feels unclear or incomplete
- Check for broken links (especially external resources)
- Review any feedback you've received
### Quarterly: Deeper Review
Every three months, dedicate a few hours to:
- Read through an entire cluster as if you were a learner
- Assess whether the progression makes sense
- Look for opportunities to clarify or trim
- Consider if any new foundational texts should be added
### Annually: Structural Review
Once a year, step back and ask:
- Does the curriculum still answer its central question?
- Have any clusters become bloated or unfocused?
- Are there gaps learners consistently mention?
- Has the field evolved in ways that require updates?
## Gathering Feedback
### Make It Easy
If you want feedback, you need to ask for it explicitly. Options:
- Add a feedback link to your site footer
- Include reflection questions that invite discussion
- Create a simple form for suggestions
- Engage with learners where they already are (forums, social media)
### Listen for Confusion
The most valuable feedback isn't "this is great" or "this is bad"—it's "I'm confused about X." Confusion reveals:
- Unclear explanations
- Missing prerequisites
- Jargon that needs definition
- Logical leaps that need stepping stones
When someone is confused, resist the urge to explain verbally. Instead, ask: "How could I rewrite this so you wouldn't have been confused?"
### Track Patterns
Individual feedback is anecdotal. Patterns are actionable. Keep a simple log:
| Date | Source | Feedback | Action Taken |
|------|--------|----------|--------------|
| 2024-03-15 | Reader email | Confused by cluster 2 lesson 3 | Rewrote introduction |
| 2024-04-02 | Own review | Lesson 5 too long | Split into two lessons |
Over time, patterns emerge: maybe all confusion relates to jargon, or lessons over 2000 words always get feedback about length.
## Types of Improvements
### Clarifying
The most common improvement is making existing content clearer:
- Rewrite convoluted sentences
- Add examples for abstract concepts
- Define terms before using them
- Break long paragraphs into shorter ones
Clarifying doesn't change what you're saying—it changes how well you say it.
### Trimming
Curricula tend to bloat. Every revision, ask:
- Does this paragraph advance the lesson's purpose?
- Is this tangent worth the distraction?
- Would a learner miss this if it were gone?
Be ruthless. If content doesn't earn its place, cut it.
### Reordering
Sometimes content is good but misplaced:
- Foundational concepts should come before specialized ones
- Abstract ideas need concrete examples nearby
- Referenced content should appear before referencing content
Read your curriculum as a learner would—sequentially—and note where you wish something had been explained earlier.
### Updating Sources
External links break. Scholarship advances. When reviewing:
- Check that all URLs still work
- Look for newer/better versions of recommended readings
- Consider if landmark new works deserve inclusion
## When to Add vs. When to Revise
The instinct when something is confusing is often "I should add more explanation." But more content creates more surface area for confusion.
**Add new content when:**
- There's a genuine gap in the progression
- A foundational text was overlooked
- The field has meaningfully advanced
**Revise existing content when:**
- Explanations are unclear
- Lessons are trying to do too much
- The framing doesn't match learner needs
When in doubt, revise. Adding is easy; maintaining is hard.
## Retiring Content
Sometimes the right move is to remove content:
- A reading that seemed foundational turns out not to be
- A lesson overlaps too much with another
- The field has moved on from certain debates
Retiring content feels wasteful, but keeping outdated or redundant content wastes learners' time. Be willing to cut.
## Version History as a Feature
Because your curriculum lives in Git, every change is tracked. This is a feature, not just a backup:
- You can see how lessons evolved
- You can revert changes that didn't work
- You can reference old versions if needed
Don't be precious about changes. Try things, measure the result, and adjust.
## The Long Game
The best curricula in the world weren't created in a weekend—they were refined over years by authors who kept showing up.
Your iteration practice doesn't need to be elaborate. It just needs to be consistent:
- Notice what's not working
- Make small improvements regularly
- Trust that small improvements compound
A curriculum that's 1% better each month will be unrecognizably improved in a year.
## Congratulations
You've completed the meta-curriculum: a curriculum about building curricula.
You now have:
1. The philosophy behind depth-first learning
2. The methodology for defining domains and finding readings
3. The technical knowledge to deploy and customize
4. The practice for maintaining and improving over time
What remains is the work: choosing your domain, curating your readings, and building something that helps others go deep.
Go build.
---
## Cluster 6: Making It Yours
Cluster URL: https://byocurriculum.dev/curriculum/making-it-yours
Description: Customize the visual design, branding, and overall feel of your curriculum site.
Your curriculum has its own identity—and the site should reflect that. This cluster covers how to customize the visual appearance without breaking anything.
You'll learn about the theming system, how to change colors and fonts, when to add rounded corners, and how styling stays separate from content so your customizations persist through updates.
### Lesson 6.1: Understanding the Theme System
Lesson URL: https://byocurriculum.dev/curriculum/making-it-yours/theme-system
Description: How the site's styling is organized and why it's safe to customize.
## How Styling Works in This Template
Every component in this site—cards, buttons, headers, code blocks—gets its colors, fonts, and sizes from CSS custom properties defined in one central file.
Here's a simplified view of how it works:
```css
/* In src/app.css */
:root {
--color-primary: #000000;
}
/* In a component */
.button {
background-color: var(--color-primary);
}
```
When you change `--color-primary` to `#2563eb` (a blue), every element using that variable updates automatically. You don't need to find and replace colors throughout the codebase.
## The Theme File
All theme variables live in `src/app.css`. Open this file and you'll see sections for:
| Section | What It Controls |
|---------|------------------|
| Colors | Primary, background, text, borders |
| Typography | Font families, weights |
| Border Radius | Corner roundness |
| Shadows | Depth effects |
| Spacing | Consistent margins and padding |
Each section has comments explaining the options and how to change them.
## What Components Use the Theme
The theme variables are used by every visual element:
**Cards and Panels**
- Cluster cards on the curriculum page
- Lesson cards in cluster views
- Concept cards within lessons
- Assignment and knowledge check sections
**Interactive Elements**
- Call-to-action buttons
- Navigation links
- Copy buttons on code blocks
**Content Elements**
- Headings and body text
- Code blocks and inline code
- Blockquotes and callouts
## The "No Surprises" Principle
The theme system follows a simple principle: changing a value should do exactly what you expect, everywhere.
- Change `--color-primary`? All primary-colored elements update.
- Change `--radius-base`? All card corners update.
- Change `--font-heading`? All headings update.
There are no hidden dependencies or surprising side effects. If you change a color, it changes that color—nothing more, nothing less.
## Trying It Out
The best way to understand the theme system is to experiment:
1. Open `src/app.css` in your editor
2. Find `--color-primary: #000000;`
3. Change it to `--color-primary: #dc2626;` (a red)
4. Save and watch the dev server hot-reload
5. See how buttons, accents, and borders all change
Now you understand the power of the theme system. The next lesson covers practical customization of colors and typography.
---
### Lesson 6.2: Customizing Colors and Fonts
Lesson URL: https://byocurriculum.dev/curriculum/making-it-yours/colors-fonts
Description: Practical guide to changing your site's color palette and typography.
## Choosing a Color Palette
Your curriculum's color palette sets its personality before readers engage with a single word. Here's how to choose wisely.
### Start With Your Primary Color
The primary color is your brand. It appears on:
- Call-to-action buttons
- Hover states
- Accent borders on callouts and concept cards
- Links (in some themes)
**Academic/Serious**: Deep blues (#1e40af), dark grays (#374151), forest green (#166534)
**Warm/Inviting**: Terracotta (#9a3412), amber (#b45309), burgundy (#991b1b)
**Modern/Tech**: Electric blue (#2563eb), purple (#7c3aed), teal (#0d9488)
### Keep Enough Contrast
Whatever primary you choose, ensure your text remains readable:
```css
/* Good: High contrast */
--color-text: #1f2937; /* Dark gray text */
--color-background: #ffffff; /* White background */
/* Bad: Low contrast */
--color-text: #9ca3af; /* Light gray text */
--color-background: #f3f4f6; /* Light gray background */
```
### Example: Academic Blue Theme
```css
:root {
--color-primary: #1e40af;
--color-primary-hover: #1e3a8a;
--color-accent: #3b82f6;
--color-background: #ffffff;
--color-surface: #ffffff;
--color-text: #1f2937;
--color-text-muted: #6b7280;
--color-border: #1e40af;
--color-border-light: #dbeafe;
}
```
This palette says "scholarly but approachable"—the blue connotes trust and authority without being cold.
## Choosing Fonts
Fonts have distinct personalities. Choose based on what your curriculum communicates.
### System Fonts (Default)
```css
--font-heading: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-body: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```
**Pros**: Loads instantly, looks native on each platform, no external dependencies
**Best for**: Technical curricula, minimalist design, performance priority
### Serif Fonts
```css
--font-heading: Georgia, 'Times New Roman', serif;
--font-body: Georgia, 'Times New Roman', serif;
```
**Pros**: Traditional, academic feel, excellent for long-form reading
**Best for**: Humanities, philosophy, literary analysis
### Custom Sans-Serif (Inter)
First, add to `src/app.html` in the ``:
```html
```
Then in `src/app.css`:
```css
--font-heading: 'Inter', system-ui, sans-serif;
--font-body: 'Inter', system-ui, sans-serif;
```
**Pros**: Modern, highly legible, excellent for web
**Best for**: Contemporary topics, design-focused curricula
### Mixed Pairing
```css
--font-heading: Georgia, 'Times New Roman', serif;
--font-body: system-ui, -apple-system, sans-serif;
```
Serif headings add gravitas; sans-serif body maintains readability.
## Testing Your Choices
After making changes, walk through the site:
1. **Homepage**: Is the hero card inviting? Do cluster cards feel cohesive?
2. **Curriculum listing**: Can you scan cluster titles easily?
3. **Lesson page**: Is body text comfortable to read? Do code blocks stand out?
4. **Mobile**: Do colors and fonts work at smaller sizes?
## Common Mistakes
### Too Many Colors
Stick to 3-4 colors maximum:
- Primary (brand)
- Background
- Text
- One accent (optional)
More than this creates visual noise.
### Low Contrast Text
Gray text on gray backgrounds might look "sophisticated" but destroys readability. Your readers will unconsciously strain and leave.
### Slow-Loading Fonts
Every custom font adds load time. If you use Google Fonts, use `display=swap` and limit weights:
```html
```
## Next Steps
Colors and fonts are the foundation. The next lesson covers advanced customization—border radius, shadows, and custom CSS for when the theme variables aren't enough.
---
### Lesson 6.3: Advanced Customization
Lesson URL: https://byocurriculum.dev/curriculum/making-it-yours/advanced-customization
Description: Border radius, shadows, and custom CSS for when theme variables aren't enough.
## Border Radius: Setting the Mood
Border radius is one of the most impactful visual changes you can make. It transforms the entire feel of the site with a single variable.
### How to Change It
In `src/app.css`, find:
```css
--radius-base: 0; /* DEFAULT: Change this to add roundness site-wide */
```
Change the value:
| Value | Effect |
|-------|--------|
| `0` | Sharp, square corners |
| `0.25rem` | Barely perceptible rounding |
| `0.5rem` | Noticeable but subtle |
| `0.75rem` | Clearly rounded |
| `1rem` | Very rounded |
### What Gets Rounded
The `--radius-base` variable affects:
- Cluster and lesson cards
- Concept and resource cards
- Assignment and knowledge check sections
- Callout boxes
- Buttons
- Code blocks
Smaller elements (badges, icons) use `--radius-sm` for proportionally smaller rounding.
### Match Radius to Content
**Philosophy, History, Literary Analysis**
Sharp corners (0) → Serious, traditional, scholarly
**Design, UX, Creative Fields**
Moderate rounding (0.5rem) → Approachable, modern, clean
**Education, Community, Wellness**
More rounding (0.75rem+) → Friendly, warm, inviting
## Shadows: Adding Depth
Shadows create the illusion that elements are floating above the page. This establishes visual hierarchy.
### Enabling Shadows
By default, all shadows are `none`. To enable them, update in `src/app.css`:
```css
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
```
### How Shadows Are Used
| Variable | Where It Appears |
|----------|------------------|
| `--shadow-sm` | Cards at rest, subtle elevation |
| `--shadow-md` | Cards on hover, interactive feedback |
| `--shadow-lg` | Reserved for modals, high-priority items |
### Shadow + Radius Combinations
**Flat + Sharp**: Minimal, Bauhaus-inspired, serious
**Flat + Rounded**: Soft, modern, clean
**Shadows + Sharp**: Corporate, Material Design
**Shadows + Rounded**: Friendly, contemporary apps
## Writing Custom CSS
When you need changes beyond variables, add custom CSS at the end of `src/app.css`.
### Safe Selectors
These classes are stable and safe to customize:
```css
/* Cards */
.book-cover /* Homepage hero */
.cluster-item /* Clusters on homepage */
.cluster-card /* Clusters on curriculum page */
.lesson-card /* Lessons in cluster view */
.concept-card /* Key concepts in lessons */
.resource-card /* Additional resources */
/* Sections */
.assignment-card /* Assignment section */
.knowledge-check-section /* Knowledge check */
.lesson-callout /* Callout boxes */
/* Buttons */
.book-cta /* Homepage CTA */
.curriculum-cta /* Curriculum page CTA */
.assignment-link /* Assignment reading link */
```
### Example: Custom Hover Effect
Add a scale effect when hovering over cards:
```css
/* Custom: Scale cards on hover */
.cluster-card:hover,
.lesson-card:hover {
transform: translateY(-2px);
}
```
### Example: Custom Heading Style
Make all lesson titles italic:
```css
/* Custom: Italic lesson titles */
.lesson-title {
font-style: italic;
}
```
### Example: Accent Color on Callouts
Change the left border color on callouts:
```css
/* Custom: Green callout accent */
.lesson-callout {
border-left-color: #22c55e;
}
```
### Best Practices for Custom CSS
1. **Comment everything**: Future you will forget why
2. **Be specific**: Use class names, not tag names
3. **Test mobile**: Custom styles can break responsive layouts
4. **Keep it minimal**: Every custom rule is maintenance
## Putting It All Together
Here's a complete theme transformation—from minimal to friendly:
```css
:root {
/* Colors: Warm and inviting */
--color-primary: #0d9488;
--color-primary-hover: #0f766e;
--color-background: #ffffff;
--color-surface: #f0fdfa;
--color-border: #99f6e4;
--color-border-light: #ccfbf1;
/* Typography: Modern sans */
--font-heading: 'Inter', system-ui, sans-serif;
--font-body: 'Inter', system-ui, sans-serif;
/* Shape: Friendly rounded */
--radius-base: 0.75rem;
--radius-sm: 0.375rem;
/* Depth: Subtle shadows */
--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.08);
}
```
This transforms the austere default into something warm and contemporary—same content, completely different feel.
## Congratulations
You've completed the customization cluster. You now understand:
- How the theme system separates styling from content
- How to change colors and typography
- When and how to use border radius and shadows
- How to write safe custom CSS
Your curriculum is now truly yours—visually distinct and aligned with your subject matter.
---
## Cluster 7: API & Data Access
Cluster URL: https://byocurriculum.dev/curriculum/api-data-access
Description: Programmatic access to your curriculum via JSON APIs, RSS feeds, and structured data.
Your curriculum isn't just a website—it's a structured data source that machines can read too.
This cluster covers the built-in APIs and data feeds that enable powerful integrations: feeding your content to AI agents, syndicating via RSS, building custom dashboards, or connecting to other tools. These are advanced features for users who want to extend their curriculum beyond the browser.
### Lesson 7.1: Understanding the Data Endpoints
Lesson URL: https://byocurriculum.dev/curriculum/api-data-access/endpoints
Description: Explore the built-in APIs that expose your curriculum as structured data.
## Available Endpoints
Your curriculum automatically provides four machine-readable endpoints. No configuration needed—they work out of the box.
| Endpoint | Format | Purpose |
|----------|--------|---------|
| `/api/curriculum.json` | JSON | Full curriculum data for applications |
| `/api/manifest.json` | JSON-LD | Schema.org structured data |
| `/feed.xml` | RSS 2.0 | Feed reader subscriptions |
| `/sitemap.xml` | XML | Search engine indexing |
All endpoints are publicly accessible and support CORS (for JSON endpoints), meaning external applications can fetch them directly from browsers.
---
## The Curriculum JSON API
This is the primary endpoint for programmatic access. It returns everything about your curriculum in a structured format.
### Basic Request
```bash
curl https://yoursite.netlify.app/api/curriculum.json
```
### Response Structure
```json
{
"$schema": "https://yoursite.netlify.app/api/schema.json",
"version": "1.0",
"generated": "2024-01-15T10:30:00.000Z",
"site": {
"name": "My Curriculum",
"url": "https://yoursite.netlify.app",
"description": "A self-directed learning path"
},
"stats": {
"totalClusters": 5,
"totalLessons": 23
},
"clusters": [
{
"id": 1,
"title": "Getting Started",
"slug": "getting-started",
"description": "...",
"url": "https://yoursite.netlify.app/curriculum/getting-started",
"lessons": [
{
"id": "1-1",
"title": "Welcome",
"slug": "welcome",
"description": "...",
"url": "https://yoursite.netlify.app/curriculum/getting-started/welcome"
}
]
}
]
}
```
### Query Parameters
| Parameter | Default | Description |
|-----------|---------|-------------|
| `cluster` | (all) | Filter to a specific cluster by slug |
| `urls` | `true` | Set to `false` to omit URL fields |
| `content` | `false` | Set to `true` to include full lesson content |
**Examples:**
Filter to a specific cluster:
```bash
curl "https://yoursite.netlify.app/api/curriculum.json?cluster=getting-started"
```
Omit URLs for a smaller payload:
```bash
curl "https://yoursite.netlify.app/api/curriculum.json?urls=false"
```
**Include full content** (for AI agents and content syndication):
```bash
curl "https://yoursite.netlify.app/api/curriculum.json?content=true"
```
With `?content=true`, each lesson includes:
- `objectives` — Learning objectives array
- `key_concepts` — Concepts with explanations (HTML)
- `assignment` — Assignment instructions (HTML)
- `knowledge_check` — Quiz questions
- `additional_resources` — External links
- `content` — Full lesson body (HTML)
---
## RSS Feed
The RSS feed makes your curriculum subscribable. When you add new lessons, subscribers get notified.
### Feed URL
```
https://yoursite.netlify.app/feed.xml
```
### What's Included
- **Clusters** appear as items with category "Cluster"
- **Lessons** appear as items categorized by their cluster name
- **Authors** are included when specified in lesson frontmatter
- **Full content** via `` — the complete lesson body as HTML
The `content:encoded` tag means RSS readers and AI agents can access the full text of each lesson, not just summaries.
### Using the Feed
Add the feed URL to any RSS reader:
- **Feedly**: Paste the URL in the search/add bar
- **NetNewsWire**: File → New Feed → paste URL
- **Inoreader**: Click the + button, paste URL
You can also use the feed with automation tools like Zapier or IFTTT to trigger actions when new content is published.
---
## Sitemap
The sitemap helps search engines discover all your content efficiently.
### Sitemap URL
```
https://yoursite.netlify.app/sitemap.xml
```
### Structure
Pages are prioritized:
- **Home page**: 1.0 (highest)
- **Curriculum index**: 0.9
- **About page**: 0.8
- **Cluster pages**: 0.8
- **Lesson pages**: 0.7
Change frequency hints:
- Static pages: monthly
- Cluster pages: weekly
- Lesson pages: monthly
### Search Console
For faster indexing, submit your sitemap to Google Search Console:
1. Go to [search.google.com/search-console](https://search.google.com/search-console)
2. Add and verify your site
3. Go to Sitemaps → Add sitemap → enter `sitemap.xml`
---
## Schema.org Manifest
This endpoint provides rich structured data that search engines and AI systems understand semantically.
### Manifest URL
```
https://yoursite.netlify.app/api/manifest.json
```
### Schema Structure
```json
{
"@context": "https://schema.org",
"@type": "Course",
"name": "My Curriculum",
"description": "...",
"hasCourseInstance": [
{
"@type": "CourseInstance",
"name": "Getting Started",
"teaches": [
{
"@type": "LearningResource",
"name": "Welcome",
"url": "..."
}
]
}
],
"_links": {
"curriculum": "https://.../api/curriculum.json",
"feed": "https://.../feed.xml",
"sitemap": "https://.../sitemap.xml"
}
}
```
The `_links` section provides discovery—any system that finds the manifest can discover all other endpoints.
---
## CORS and Caching
### Cross-Origin Access
The JSON endpoints include CORS headers:
```
Access-Control-Allow-Origin: *
```
This means JavaScript running on any domain can fetch your curriculum data. Useful for embedding widgets or building external tools.
### Caching
All endpoints return a 1-hour cache header:
```
Cache-Control: max-age=3600
```
This balances freshness with performance. After editing content, it may take up to an hour for cached responses to update.
---
## Next Steps
Now that you understand what's available, the next lesson explores practical use cases: feeding content to AI agents, building custom dashboards, and automating workflows.
---
### Lesson 7.2: Use Cases and Integrations
Lesson URL: https://byocurriculum.dev/curriculum/api-data-access/use-cases
Description: Practical applications for the curriculum APIs—from AI agents to custom dashboards.
## Why Expose Your Curriculum as Data?
A curriculum website is valuable. A curriculum that machines can read is *powerful*.
When your content is available as structured data:
- **AI agents** can learn your material and help students
- **Automation** can spread the word when you publish
- **Custom tools** can build on top of your content
- **Other systems** can integrate without manual work
The APIs are already built. This lesson shows you what to do with them.
---
## Use Case 1: AI Tutoring Assistant
### The Concept
Imagine an AI assistant that knows your curriculum deeply—not just the text, but the structure. It can:
- Recommend which lesson to read based on a question
- Explain how topics connect across clusters
- Quiz learners on key concepts
- Suggest what to study next
### How to Build It
**With Claude Projects:**
1. Go to [claude.ai](https://claude.ai) and create a new Project
2. In Project Knowledge, add a new file
3. Fetch your curriculum: `curl https://yoursite.netlify.app/api/curriculum.json > curriculum.json`
4. Upload `curriculum.json` to the project
5. Start chatting—Claude now knows your entire curriculum
**Example prompts to try:**
- "What topics does this curriculum cover?"
- "I want to learn about [topic]. Which lesson should I start with?"
- "Summarize the key concepts from the Getting Started cluster"
- "Create a quiz based on lesson 2 of cluster 1"
**With Custom GPTs:**
1. Go to ChatGPT and create a new GPT
2. In the configuration, under Knowledge, upload your curriculum JSON
3. Or configure it to fetch from your API URL
4. Set instructions like: "You are a tutor for this curriculum. Help students navigate and understand the material."
### Why This Works
The JSON structure tells the AI:
- What clusters exist and how they're ordered
- What lessons belong to each cluster
- Titles, descriptions, and slugs for linking
- The overall scope and progression
This is far better than the AI just reading your website—it understands the *structure*.
---
## Use Case 2: Social Media Automation
### The Concept
Every time you publish a new lesson, automatically:
- Tweet about it
- Post to LinkedIn
- Send a newsletter
- Notify a Discord server
### How to Build It
**With Zapier:**
1. Create a Zapier account (free tier works)
2. Create a new Zap
3. **Trigger**: Choose "RSS by Zapier" → "New Item in Feed"
4. **Feed URL**: `https://yoursite.netlify.app/feed.xml`
5. **Action**: Choose your destination (Twitter, Slack, Email, etc.)
6. **Configure**: Use the feed item's title, link, and description
**Example Zap: RSS → Twitter**
```
When: New item in RSS feed
Post to Twitter:
"New lesson published: {{title}}
{{link}}
#learning #curriculum"
```
**With Make (Integromat):**
Similar flow—RSS module as trigger, social media as action. Make offers more complex branching if you want different actions for clusters vs. lessons.
**With IFTTT:**
1. Create an IFTTT applet
2. "If RSS feed has new item" → "Then post to Twitter/Slack/etc."
3. Simple but effective for basic notifications
### Pro Tips
- Filter by category to only announce lessons (not clusters)
- Add a delay so you can catch mistakes before auto-posting
- Include hashtags relevant to your curriculum topic
---
## Use Case 3: Progress Tracking App
### The Concept
Build a companion app where learners:
- See all available lessons
- Mark lessons as complete
- Track their progress through clusters
- Get suggestions for what to learn next
### How to Build It
**Simple Browser-Based Tracker:**
```html
My Learning Progress
Progress Tracker
```
This saves progress to the browser's local storage. Click a lesson to mark it complete.
**More Advanced Options:**
- Add a backend to sync progress across devices
- Build a React Native app for mobile
- Integrate with a learning management system
- Add spaced repetition for knowledge checks
---
## Use Case 4: Embedding on Other Sites
### The Concept
Display your curriculum on another website—a blog, documentation site, or partner page.
### How to Build It
**Embeddable Widget:**
```html
```
Anyone can add this snippet to their site to display your curriculum structure with links back to your site.
---
## Use Case 5: Analytics and Visualization
### The Concept
Visualize your curriculum's structure and growth over time.
### Ideas
- **Curriculum map**: D3.js visualization showing clusters and lessons as a network
- **Growth chart**: Track how many lessons you've added over time
- **Coverage analysis**: See which topics have the most/least content
- **Complexity metrics**: Analyze lesson lengths, concept counts, etc.
### Simple Stats Dashboard
```javascript
fetch('https://YOURSITE.netlify.app/api/curriculum.json')
.then(r => r.json())
.then(data => {
console.log('Curriculum Stats:');
console.log(`Total Clusters: ${data.stats.totalClusters}`);
console.log(`Total Lessons: ${data.stats.totalLessons}`);
console.log(`Average lessons per cluster: ${(data.stats.totalLessons / data.stats.totalClusters).toFixed(1)}`);
data.clusters.forEach(c => {
console.log(` ${c.title}: ${c.lessons.length} lessons`);
});
});
```
---
## Use Case 6: Content Syndication
### The Concept
Feed your curriculum into other platforms:
- **Learning Management Systems** (Moodle, Canvas): Import course structure
- **Documentation generators**: Pull content into docs
- **Email courses**: Drip lessons to subscribers
- **Podcast show notes**: Link to relevant lessons
### How It Works
Most platforms that import content accept:
- **RSS** for sequential content
- **JSON** for structured data
- **OPML** for outlines (you could generate this from the API)
The key is that your curriculum is the *source of truth*. Other systems read from it rather than duplicating content.
---
## Best Practices
### Rate Limiting
The API caches for 1 hour. If you're building a high-traffic application, cache responses on your end too.
### Error Handling
Always handle fetch errors gracefully:
```javascript
fetch(url)
.then(r => {
if (!r.ok) throw new Error('Failed to fetch');
return r.json();
})
.catch(err => {
console.error('Could not load curriculum:', err);
// Show fallback UI
});
```
### Attribution
If you build something cool with someone else's curriculum API, consider crediting them and linking back.
---
## What Will You Build?
The APIs are ready. The use cases are endless:
- A study buddy AI that knows your material
- Automatic social posting when you publish
- A mobile app for learning on the go
- A dashboard to track your curriculum's growth
- Integrations with tools your audience already uses
Start with one simple integration. Once you see how easy it is, you'll think of many more.
---
### Lesson 7.3: NotebookLM Integration
Lesson URL: https://byocurriculum.dev/curriculum/api-data-access/notebooklm
Description: Use Google's NotebookLM to consume your curriculum or generate new content from source readings.
## Two Ways to Integrate
NotebookLM and your curriculum can work together in both directions. Your curriculum provides structured data that NotebookLM can consume. NotebookLM's analysis capabilities can help you create better curriculum content.
| Direction | Input | Output |
|-----------|-------|--------|
| **Consumer** | Your curriculum data | Queries, summaries, audio overviews |
| **Generator** | Your source readings | Insights for writing lessons |
Both leverage the same insight: structured, well-organized content is easier for AI to work with.
---
## Direction 1: NotebookLM as Curriculum Consumer
### Adding Your Curriculum
NotebookLM accepts URLs as sources. Your curriculum provides several entry points:
#### Option A: Full Curriculum JSON
```
https://yoursite.netlify.app/api/curriculum.json?content=true
```
This gives NotebookLM your entire curriculum—all clusters, lessons, objectives, key concepts, and body content in one structured file.
#### Option B: Individual Lesson URLs
Add specific lesson pages as sources. Useful when you want to focus on a particular cluster or compare specific lessons.
#### Option C: RSS Feed
```
https://yoursite.netlify.app/feed.xml
```
The RSS feed includes full lesson content via `content:encoded`. Some tools prefer RSS format.
### What You Can Do
Once your curriculum is in NotebookLM:
**Query across lessons:**
- "What prerequisites does Lesson 5 assume?"
- "Which lessons mention [specific concept]?"
- "How does the Getting Started cluster relate to the advanced material?"
**Find hidden connections:**
- "What themes appear across multiple clusters?"
- "Are there concepts that should be introduced earlier?"
- "What's missing from this curriculum?"
**Generate summaries:**
- "Summarize each cluster in one sentence"
- "What are the 10 most important concepts in this curriculum?"
- "Create a study guide for cluster 3"
### Audio Deep Dives
NotebookLM can generate podcast-style audio overviews. This is particularly useful for curricula:
1. Select a cluster's lessons as sources
2. Click "Generate Audio Overview"
3. NotebookLM creates a conversational discussion of the material
**Use cases:**
- Preview audio for learners before they start reading
- Review audio for learners who've completed a cluster
- Accessibility alternative for auditory learners
- Companion content for commutes or workouts
The structured nature of your lessons (clear objectives, defined key concepts) gives NotebookLM better material to synthesize.
---
## Direction 2: NotebookLM as Curriculum Generator
This is where things get interesting. Instead of consuming your finished curriculum, NotebookLM can help you *create* it.
### The Problem NotebookLM Solves
Writing good curriculum requires deep engagement with source material:
- Reading multiple texts
- Identifying what's essential vs. supplementary
- Finding connections across readings
- Translating expert language into accessible explanations
This is time-consuming. NotebookLM can handle the analysis while you focus on curation and judgment.
### The Workflow
```
┌─────────────────┐
│ Upload Sources │ PDFs, articles, book chapters
└────────┬────────┘
▼
┌─────────────────┐
│ Query Insights │ Key concepts, connections, questions
└────────┬────────┘
▼
┌─────────────────┐
│ Export Findings │ Copy useful responses
└────────┬────────┘
▼
┌─────────────────┐
│ Feed to Prompts │ Use as input for lesson structure
└────────┬────────┘
▼
┌─────────────────┐
│ Generate Lesson │ Write with richer grounding
└────────┬────────┘
▼
┌─────────────────┐
│ Publish via CMS │ Add to curriculum
└─────────────────┘
```
### Step 1: Upload Your Sources
Create a NotebookLM notebook for each cluster or topic area. Add:
- The primary readings you want to assign
- Supplementary texts that provide context
- Papers or articles that informed your thinking
NotebookLM handles PDFs, Google Docs, web pages, and pasted text.
### Step 2: Query for Curriculum Insights
Ask questions that help you structure lessons:
**For identifying key concepts:**
```
"What are the 5-7 most important concepts a beginner
should understand from these readings?"
```
**For finding connections:**
```
"What themes or ideas appear across multiple sources?
How do they relate to each other?"
```
**For drafting explanations:**
```
"Explain [concept] in accessible language for someone
new to this field. Use concrete examples."
```
**For generating questions:**
```
"What reflection questions would help someone deeply
engage with these readings?"
```
**For structuring progression:**
```
"If teaching this material, what order would you
introduce these concepts? What builds on what?"
```
### Step 3: Export and Refine
NotebookLM's responses become raw material for your lessons. Copy the useful parts:
- Key concepts become your lesson's `key_concepts` section
- Explanations become starting points for your lesson body
- Questions become `knowledge_check` items
- Structure suggestions inform your cluster organization
### Step 4: Apply Editorial Judgment
NotebookLM analyzes. You curate.
**You decide:**
- Which concepts are truly essential vs. nice-to-know
- What order makes sense for *your* audience
- What tone and level of detail fits your curriculum
- Which connections are meaningful vs. superficial
NotebookLM gives you a head start. It doesn't replace your expertise and judgment about what belongs in the curriculum.
### Step 5: Generate and Publish
Take NotebookLM's insights and feed them into your lesson creation process:
1. Use the structure suggestions to plan your lesson
2. Expand the explanations in your own voice
3. Format for your CMS (frontmatter, markdown body)
4. Add via the admin interface or directly to the content files
---
## Example: Creating a New Lesson
Let's say you're adding a lesson on "Systems Thinking" to a philosophy curriculum.
**In NotebookLM:**
Upload:
- Donella Meadows' "Thinking in Systems" (excerpts)
- A paper on feedback loops
- An article on emergence
Query:
```
"What key concepts from systems thinking would be most
valuable for philosophy students? Focus on concepts that
connect to philosophical questions about causation,
reductionism, and emergence."
```
NotebookLM responds with concepts like feedback loops, stocks and flows, emergence, leverage points—with explanations grounded in your sources.
**In your CMS:**
Create a new lesson with:
- `key_concepts` based on NotebookLM's analysis
- `objectives` refined from what NotebookLM identified as important
- Body content expanding on the explanations, in your voice
- `additional_resources` pointing to the original sources
The lesson is grounded in actual readings, not generated from scratch.
---
## Combining Both Directions
The most powerful workflow combines consumption and generation:
1. **Generate** new lessons using NotebookLM + source readings
2. **Publish** to your curriculum via CMS
3. **Consume** your updated curriculum in a new NotebookLM notebook
4. **Query** for gaps, connections, and improvements
5. **Iterate** based on insights
Your curriculum becomes a living system—NotebookLM helps you both build it and understand it.
---
## Limitations to Know
**NotebookLM as consumer:**
- Source limits (currently ~50 sources per notebook)
- May not handle very large JSON files well
- Audio generation quality varies with source clarity
**NotebookLM as generator:**
- Outputs need human review and editing
- Can miss nuance that close reading would catch
- Doesn't know your specific audience
**General:**
- Requires Google account
- Sources are stored with Google
- Features change as the product evolves
The integration is powerful but not magic. Use it to augment your process, not replace your judgment.
---
_End of course. 23 lessons across 7 clusters._