Authors' guide for editing and maintaining the curriculum site.
Live site: https://navigation-games.github.io/curriculum/
Most editors and reviewers should not edit the repo directly. Instead, make your own notes on needed changes, whether detailed wordsmithing or general issues, and share them with an editor who knows the repo structure (currently Barb). The editor makes the actual changes, sometimes with assistance from Claude, and verifies that the build and site are correct.
This keeps the repo clean, avoids accidental edits to generated files, and lets the editor handle structural concerns (build scripts, cross-references, vocabulary sync) that a content reviewer shouldn't need to worry about.
The curriculum has lived in GitBook and then Google Sites. Both worked well for writing and sharing content, but as the curriculum grew we hit a consistency problem: each activity exists in multiple forms (one-pager, full description, script, lesson plan reference, vocabulary list) and keeping them in sync across formats and across activities was manual and error-prone.
We moved to Docusaurus + GitHub because we are at a stage of curriculum development where we need to edit across the entire curriculum for consistency, overall pedagogical flow, and getting all the details right prior to final publication. Specifically, this solution gives us:
- Content is structured and reusable. Activity metadata (goals, vocabulary, materials, reflection questions) is stored once and rendered into multiple views: full activity page, printable one-pager, lesson plan card, etc. A change to vocabulary propagates everywhere.
- Consistency can be checked programmatically. The build script and tests scan the structured content to flag missing sections, inconsistent terminology, or activities that have drifted out of sync.
- Multiple views from one source. The same content file produces both the full interactive page and the compact one-pager. No separate documents to reconcile.
- Version history and collaboration. Git tracks every change, who made it, and why. Multiple editors can work in parallel without overwriting each other.
- AI-friendly format. Plain-text Markdown and structured metadata work well with AI tools for drafting new content, generating explanatory videos, writing scripts, and keeping language consistent across activities.
The tradeoff is that editing requires working with text files and git instead of a WYSIWYG editor. To make this easier, authors edit clean Markdown files (no markup or code), and a build script generates the formatted site pages.
Content lives in several places depending on what you are editing. This section is the complete map.
Activities and lesson plans are written as simple Markdown in content/ and transformed by a build script into the formatted site pages in site/docs/. The build script exists so that:
- Authors write plain Markdown, not JSX or React components. The build script adds the tabs, view toggles, activity cards, and other interactive elements.
- One file produces two views. The same content file generates both the full interactive page and the compact printable one-pager. No separate documents to keep in sync.
- Lesson materials are merged automatically. When a lesson references activities, the build script pulls in each activity's materials list so editors don't have to duplicate them.
- Content is validated. The build script catches missing sections, missing metadata, and structural problems before they reach the site.
Edit the source files in content/, then run the build to update the site pages. Never edit the generated files directly.
| What | Edit here | Generates |
|---|---|---|
| Activities (Boundary Run, Animal-O, etc.) | content/activities/*.md |
site/docs/activities/core/*.md |
| Lesson plans (Grade 3-5) | content/lessons/school/grade-3-5/*.md |
site/docs/lessons/school/grade-3-5/*.md (numbered files only) |
Generated files have a comment at the top: {/* AUTO-GENERATED — do not edit directly */}
These pages are written by hand and are not generated by the build script. Edit them directly.
About pages:
| Page | File |
|---|---|
| About (overview) | site/docs/about/index.md |
| How to Use This Site | site/docs/about/how-to-use-this-site.md |
| Acknowledgments | site/docs/about/acknowledgments.md |
| Copyright and License | site/docs/about/copyright.md |
Reference pages:
| Page | File |
|---|---|
| Glossary | site/docs/reference/glossary.md |
| Materials Index | site/docs/reference/materials.md |
| Resources | site/docs/reference/resources.md |
| Activities Index | site/docs/reference/activities-index.mdx |
| Frameworks (overview) | site/docs/reference/frameworks/index.md |
| PE Standards | site/docs/reference/frameworks/pe-standards.md |
| Experiential Learning | site/docs/reference/frameworks/experiential-learning.md |
| Social-Emotional Learning | site/docs/reference/frameworks/social-emotional-learning.md |
| Orienteering Dev Model | site/docs/reference/frameworks/orienteering-development-model.md |
| Leave No Trace | site/docs/reference/frameworks/leave-no-trace.md |
Curriculum index pages (landing pages for each grade band or program):
| Page | File |
|---|---|
| School overview | site/docs/lessons/school/index.md |
| Grade 3-5 overview | site/docs/lessons/school/grade-3-5/index.md |
| Grade K-2 overview | site/docs/lessons/school/grade-k-2/index.md |
| Grade 6+ overview | site/docs/lessons/school/grade-6-plus/index.md |
| Camp overview | site/docs/lessons/camp/index.md |
| Camp Intro | site/docs/lessons/camp/intro/index.md |
| Camp Full | site/docs/lessons/camp/full/index.md |
| Activities overview | site/docs/activities/core/index.md |
| Equipment overview | site/docs/equipment/index.md |
| SI Timing | site/docs/equipment/si-timing.md |
Landing pages (the main entry points for different audiences):
| Page | File |
|---|---|
| Home | site/src/pages/index.tsx |
| School landing | site/src/pages/school.mdx |
| Camp landing | site/docs/lessons/camp/index.md |
| Quick Start | site/src/pages/quick-start.mdx |
Some content is stored in TypeScript data files that feed into interactive components. These are editable but require basic familiarity with the format (arrays of objects with quoted strings).
| Data | File | Used by |
|---|---|---|
| Glossary definitions | site/src/components/VocabLink/glossaryData.ts |
Vocabulary popups on activity and lesson pages |
| Materials catalog | site/src/components/MaterialLink/materialsData.ts |
Materials popups on activity and lesson pages |
| Activities summary | site/src/components/ActivitiesTable/activitiesData.ts |
Activities index table, activity card popups in lessons |
When you add or change a glossary term, update both glossaryData.ts and site/docs/reference/glossary.md to keep them in sync. Similarly, update both materialsData.ts and site/docs/reference/equipment/materials.md for materials.
One data file is auto-generated and should never be edited by hand: site/src/components/ActivityLink/activitySummaries.ts (the activity popup summaries on lesson pages). The build script regenerates it from content/activities/, so edit the activity's Description and frontmatter instead.
Activity photos and diagrams go in site/static/img/activities/. Use lowercase-kebab-case filenames (e.g., animal-o.png, boundary-run.png). Images are referenced by path in content files and data files.
Video script drafts live in site/docs/editors/video-scripts/ (hand-maintained; published under For Editors). One script per Grade 3-5 lesson plus one per major activity. They are working documents for video production and were aligned with the current lesson structure in July 2026.
Activity files live in content/activities/. Here is the structure:
# Animal-O
---
subtitle: Clue Sheet Orienteering
tagline: Use a clue sheet to find checkpoints in order
epigraph: In orienteering, you find checkpoints in order using clue sheets
sidebar_position: 3
tags: [core, level-1]
time: 15-30 minutes
space: Gym, schoolyard, or local park
materials:
- Animal-picture checkpoints
- Clue sheets
setup: Place animal-picture checkpoints around the defined space
---
## Description
One or two sentences describing what the activity is.
## Goals
- Short: Identifying landmarks
Long: Understand that landmarks are features in terrain that are easy to find
- Short: Following clue sheets
Long: Use a clue sheet to visit checkpoints in the correct order
## Vocabulary
- Checkpoint
A marked location that you navigate to
- Clue sheet
A list showing which checkpoints to visit, in order
## Setup
Detailed setup instructions here.
## Steps
1. Short: Pick up a clue sheet
Long: Pick up a clue sheet at the start triangle
2. Short: Find each animal in order
Long: Find and confirm each animal in order using the clue sheet
3. Short: Return to the finish
Long: Return to the finish after the last checkpoint
## Delivery
1. Run the boundary
2. Find the animals in order
## Reflection
- What was hard about this activity?
- How did you know you were at the right checkpoint?
## Extensions
- Try it without a clue sheet
- Race against the clockKey conventions for activities:
- The
# Titleline at the top sets the page title - Frontmatter goes between
---markers (YAML format) - Goals use the
Short:/Long:format. The short version appears on the one-pager, the long version on the full page. Put theLong:line indented on the next line afterShort: - Steps also support the
Short:/Long:format (same as goals). Short steps appear on the one-pager, long steps on the full page. Plain numbered steps (without Short:/Long:) are used for both views. - Vocabulary terms are a word followed by an indented definition on the next line, separated by blank lines
- Sections use
## Heading(two hashes)
Lesson files live in content/lessons/school/grade-3-5/. They are simpler than activities:
# 3 - Explore & Find
---
tagline: There are things out there; go find them and come back
sidebar_position: 3
time: 30-45 minutes
space: Gym, schoolyard, or local park
materials:
- Checkpoints (cones with animal pictures)
setup: Place animal checkpoints around the space within the boundary
vocabulary:
- Boundary
- Gathering signal
- Checkpoint
activities:
- title: Boundary Run
description: Review the boundary (quick refresher).
link: /activities/core/boundary-run
tag: core
- title: Explore & Find
description: In pairs, explore to find animal checkpoints.
link: /activities/core/animal-o
tag: core
---
## Goals
### Orienteering Goals
- Explore a space and find checkpoints within the boundary
- Return on the gathering signal
### PE Standards (SHAPE America)
- Demonstrate locomotor skills (S1.E1, S1.E2)
- Engage actively in class (S3.E2)
## Delivery
1. [**Boundary Run**](/activities/core/boundary-run): quick review of the boundary
2. Pair up
3. [**Explore & Find**](/activities/core/animal-o): explore to find animal checkpoints
## Compact Delivery
1. **Boundary Run**: quick review of the boundary
2. Pair up
3. **Explore & Find**: explore to find animal checkpoints
## Reflection
- How many animals did you find?
- Where were the animals?
## Extensions
- Move the checkpoints to new locations and start over
- Have students draw a map of the areaKey conventions for lessons:
- The
activities:list in frontmatter generates clickable cards on the lesson page - Goals are plain bullets (no Short:/Long: needed since lessons show the same text in both views)
## Deliveryis the full version. It can include markdown links like[**Boundary Run**](/activities/core/boundary-run). These links appear on the full page but are stripped in the one-pager.## Compact Deliveryis optional. If present, it replaces the delivery section on the one-pager. Use it when the full delivery has extra detail that doesn't belong on a one-pager. If omitted, the full delivery is used for both views.- Vocabulary in lessons is a simple list of terms (no definitions needed; those live on the activity pages)
# Generate site pages from content files
node scripts/build-content.js
# Start local preview (from the site/ directory)
cd site
npm install # first time only
npm startThe preview runs at http://localhost:3000/curriculum/. Changes to content files require re-running the build script, then the dev server will pick up the changes automatically. Changes to directly-edited pages and data files are picked up by the dev server automatically (no build step needed).
The build script validates your content files and reports problems:
- Errors (build fails): missing title, missing tagline, missing required sections (Description, Goals for activities; Goals, Delivery for lessons), goals section with no goals
- Warnings (build succeeds but check these): missing time, space, vocabulary, sidebar_position
The build script automatically merges materials from a lesson's referenced activities into the lesson's materials list. Here's how it works:
- The script reads the
materials:list from every activity file incontent/activities/ - For each lesson, it looks at the
activities:list in frontmatter and finds matching activity materials by title - It adds any activity materials that aren't already in the lesson's own
materials:list (deduplicating by material type, so "4 colored landmark cones" and "4 colored cones" aren't both listed)
This means you only need to list materials in the lesson's frontmatter that are not already listed in the referenced activities. Activity-specific materials are pulled in automatically. If you need to override or exclude an activity's material for a particular lesson, list your preferred version in the lesson's materials: field and the duplicate will be skipped.
Error messages include the filename and what's wrong, for example:
1 error(s):
animal-o.md: Missing required section: ## Description
You can edit content files directly on GitHub.com without any local setup:
- Navigate to the file (see "Where to Edit" above for which file to change)
- Click the pencil icon to edit
- Make your changes and commit
The site auto-publishes when you push to main. A GitHub Actions workflow builds and deploys to GitHub Pages (takes 1-2 minutes).
Note: editing on GitHub skips the content build step. For generated activity and lesson pages to update, someone needs to run node scripts/build-content.js and commit the result. (We plan to automate this with a GitHub Action.) Directly-edited pages update immediately on deploy.
If someone edits a file on GitHub while you are editing locally, your next git push will be rejected because the remote has changes you do not have. This is normal and safe. To resolve it:
git pull --rebaseThis downloads the remote changes and replays your local commits on top. If you and the other person edited different files, it just works. If you both edited the same file, git will ask you to resolve the conflict (pick which version to keep for the overlapping lines).
Good habit: run git pull before you start editing and before you push. This keeps conflicts small and easy to resolve.
If you are not comfortable with git, the simplest workflow is: edit on GitHub.com (one file at a time, commit each change), and let the other person do the same. GitHub handles the merging automatically when you edit through the web interface.
content/ Editable content sources
activities/ Activity content (Animal-O, Boundary Run, etc.)
lessons/school/ Lesson plans by grade band
lessons/camp/ Camp lesson plans (intro and skill development)
scripts/ Build script (content -> site pages)
site/ Docusaurus site
docs/ Site pages
activities/core/ Generated activity pages (don't edit)
lessons/school/ Generated lesson pages + hand-edited index pages
equipment/ Setup guides, SI timing (edit directly)
reference/ Glossary, materials, frameworks, etc. (edit directly)
src/
components/ React components and data files
pages/ Landing pages (home, school, camp, quick-start)
static/img/ Images (activity photos, diagrams, logos)
background/ Source materials, reference PDFs
notes/ Curriculum decisions, open questions
Activities describe one thing you do. They own setup, delivery, vocabulary, and goals. They do NOT own sequencing or reflection (that's the lesson plan's job).
Lesson Plans compose activities into sequences with transitions and reflection.
Landing Pages (school, camp, quick-start) route audiences to the right lesson plans.
These are generated or managed by tools. Editing them directly will be overwritten.
site/docs/activities/core/*.md(exceptindex.md) - generated fromcontent/activities/site/docs/lessons/school/grade-3-5/1-*.mdthrougha-*.md- generated fromcontent/lessons/site/build/- production build outputnode_modules/- npm dependenciespackage-lock.json- auto-managed by npm
Generated files have a comment at the top: {/* AUTO-GENERATED — do not edit directly */}. If you see that comment, find the corresponding source file in content/ and edit there instead.
- Filenames: lowercase-kebab-case
- No em-dashes in writing. Split into separate sentences or use other connectors.
The AI lesson plan advisor (ai-advisor/system-prompt.md) holds a condensed copy of the curriculum. It does not update itself. Periodically, and after any round of curriculum editing, revisit the prompt and check it against what changed: lesson tables, activity names and descriptions, links, and naming decisions. A detailed checklist is in the editing guide under "Keep the Advisor in Sync."
The build script also regenerates ai-advisor/site-map.md, a list of every public page with a one-line description that the advisor appends to its prompt, so page-level routing stays current automatically. But none of it reaches the live advisor on git push: prompt and site map changes take effect only after rebuilding and redeploying the Cloud Run container (see ai-advisor/README.md).
- GitBook published site
- GitBook source repo
- Current school curriculum (Google Sites)
- Current camp curriculum (Google Sites)
For build tooling details, component documentation, and WSL troubleshooting, see DEVELOPMENT.md.
For what's done, what's next, and known gaps, see ROADMAP.md.