Creating a new workshop

Navigation: 

This guide walks you through creating a new workshop from idea to pull request. Before you begin, complete the Getting Started setup (Git, Hugo, fork) and read the Site Architecture overview.

Our philosophy

Nuevo Foundation workshops should feel like guided adventures, not textbooks. Every workshop tells a story that students follow at their own pace. The best workshops are:

Learn from our best workshops

Study these gold-standard workshops before building your own:

Web basics (HTML/CSS) — content/english/web-basics/

Python turtle — content/english/python-turtle/

EarSketch (Python and JS blocks) — content/english/python-earsketch/

Step 1: scaffold your workshop

Use the scaffold script to generate the correct directory structure and template files. Do not create workshop files manually — the scaffold ensures correct Hugo frontmatter, file naming, and directory layout.

Requirement: Python 3.7 or later. Verify with python --version (or python3 --version on macOS/Linux).

Run this from the root of the workshops repository:

python tools/new-workshop.py --name "my-workshop" --title "My Workshop"

Use --dry-run first to preview what would be created without writing any files:

python tools/new-workshop.py --name "my-workshop" --title "My Workshop" --dry-run

This generates the standard starter structure:

content/english/my-workshop/
├── _index.md          ← Landing page (intro, prerequisites, TOC)
├── activity-1.md      ← First activity
├── activity-2.md      ← Second activity
├── activity-3.md      ← Third activity
├── answer-key.md      ← Answer key (hidden from navigation)
└── media/
    └── .gitkeep       ← Folder for screenshots and images

Scaffold options

OptionDefaultDescription
--name(required)Directory name in kebab-case (e.g. python-web-scraping)
--title(required)Display title (e.g. "Python: Web Scraping")
--activities or -n3Number of activity files to generate (1 to 25)
--difficultyBeginnerBeginner, Intermediate, or Advanced
--description(empty)Short description for the landing page
--prereq"None"Prerequisite workshop name
--iconfas fa-codeFont Awesome icon class
--language or -lenglishLanguage folder (e.g. espanol, korean)
--no-answer-key(off)Skip generating the answer key file
--dry-run(off)Preview without writing files

Example: intermediate workshop with 5 activities

python tools/new-workshop.py \
  --name "python-web-scraping" \
  --title "Python: Web Scraping" \
  --activities 5 \
  --difficulty Intermediate \
  --prereq "Python Basics" \
  --description "Learn to scrape data from websites using Python"

Step 2: fill in your content

Open the generated files and replace the placeholder text:

  1. _index.md (landing page): Write the introduction. Set up your story, explain what students will learn, and list prerequisites. The `

shortcode at the bottom auto-generates the table of contents — leave it in place. 2. **activity-N.md** files: Write step-by-step instructions for each activity. Replace placeholder titles with descriptive names (e.g. “Activity 1: Drawing shapes”). Include a challenge at the end of each activity. 3. **answer-key.md**: Add solutions for every activity challenge. This file has hidden: true in its frontmatter so it won't appear in navigation. 4. **media/**: Add screenshots, diagrams, or images. Use media/image-name.pngin_index.mdand../media/image-name.pngin activity pages (activity pages render one level deeper in Hugo, so they need../` to reach the media folder).

For formatting help, see the Formatting and Code and interactivity guides.

Step 3: preview locally

From the workshops directory:

hugo server -D

Open http://localhost:1313/ and navigate to your workshop. Click through every activity to check that content renders correctly, images load, and navigation works.

Step 4: open a pull request

git checkout -b workshop/my-workshop
git add content/english/my-workshop/
git commit -m "Add my-workshop workshop"
git push --set-upstream origin workshop/my-workshop

Then open a pull request from your fork to the main repo.

Workshop quality checklist

Use this checklist before submitting your PR. Reviewers will check the same items.

Landing page (_index.md)

` shortcode present at bottom for auto-generated table of contents

Activities (activity-N.md)

Answer key (answer-key.md)

Media and assets

Writing and language

Hugo and build

PR review checklist (for reviewers)

When reviewing a workshop PR:

  1. Does it actually run? Follow the instructions yourself. Can a student get working code?
  2. Answer key complete? Map every activity’s challenge to its answer
  3. Images load? Check for case-sensitivity issues
  4. Language quality? Read for typos, grammar, and accuracy
  5. Self-paced friendly? Could a student complete this without a teacher?
  6. Fun factor? Is the theme engaging? Can students personalize it?
  7. Accessibility? Descriptive alt text on all images, clear instructions
  8. Progressive difficulty? Activities build on each other, one concept at a time
  9. Hugo build clean? Run hugo server -D and check for warnings
  10. Walk through it yourself. Complete the workshop as a student would, start to finish

The Hugo theme automatically adds a Nuvi “You did it! Workshop complete” celebration to the last page of every workshop. You do not need to create a separate conclusion file. If your workshop has a special story ending, you can optionally add a conclusion.md page.

Resources