Skip to content

Add workshop scaffold script for new contributors and interns#634

Open
beagandica wants to merge 5 commits intoNuevoFoundation:masterfrom
beagandica:tools/workshop-scaffold
Open

Add workshop scaffold script for new contributors and interns#634
beagandica wants to merge 5 commits intoNuevoFoundation:masterfrom
beagandica:tools/workshop-scaffold

Conversation

@beagandica
Copy link
Copy Markdown
Member

Summary

Workshop scaffold script for creating new workshop directories with all required template files. Designed for summer interns and new contributors.

Usage

python tools/new-workshop.py --name "python-web-scraping" --title "Python: Web Scraping"
python tools/new-workshop.py --name "my-workshop" --title "My Workshop" --activities 5 --difficulty Intermediate
python tools/new-workshop.py --name "my-workshop" --title "My Workshop" --dry-run
python tools/new-workshop.py --name "my-workshop" --title "My Workshop" -l espanol

What it generates

content/{language}/{workshop-name}/
  _index.md          Main workshop page (title, description, TOC)
  activity-1.md      Activity templates (numbered, weighted)
  activity-2.md
  activity-3.md
  answer-key.md      Solutions template (hidden: true)
  media/.gitkeep     Asset folder (tracked by git)

Features

  • Validation: kebab-case names, activity limits (1-25), language directory check
  • Safety: --dry-run previews without writing, checks for existing directories
  • YAML escaping: Handles quotes in titles safely
  • Cross-platform: Works on Windows, Mac, Linux
  • CWD detection: Auto-resolves repo root if run from tools/ directory
  • Hugo-compatible: Valid frontmatter, shortcodes, and file structure
  • No dependencies: Python 3 stdlib only (from __future__ import annotations for 3.7+ compat)

QA

  • 10-model review (Opus, Sonnet, GPT-5.4, GPT-5.2, Haiku)
  • Bugs found and fixed: YAML injection, Python 3.10+ compat, CWD detection, download field removed, dynamic answer-key weight, .gitkeep for empty dirs, activity cap, input validation

@beagandica beagandica self-assigned this Apr 25, 2026
beagandica pushed a commit to beagandica/workshops that referenced this pull request Apr 27, 2026
Merge comprehensive workshop creation guidance from WORKSHOP-STANDARDS.md
(PR NuevoFoundation#597) into the /guidelines/ pages so they are the one-stop shop for
contributors. PR NuevoFoundation#597 can now be closed.

new-workshops.md rewritten from 3-line stub to comprehensive guide:
- Workshop philosophy (story-driven, personalizable, self-paced, progressive)
- Gold standard examples (web-basics, python-turtle, earsketch)
- Scaffold script workflow (integrated from PR NuevoFoundation#634)
- Comprehensive quality checklist (36 items across 6 categories)
- PR review checklist (10 items for reviewers)
- Cross-links to all specialist guideline pages

Also updated:
- images-and-gifs.md: standardized on media/ convention (scaffold default),
  added backward-compat note for older workshops using img/,
  fixed shortcode delimiter consistency
- translation-volunteer.md: added Spanish tu-conjugation note
- _index.md: aligned all link texts with target page titles (sentence case)

10-model QA + 3 clean convergence passes.

Co-authored-by: Copilot <[email protected]>
Beatris Mendez Gandica and others added 4 commits April 28, 2026 18:51
Generates a complete workshop directory with template files:
- _index.md with Hugo frontmatter and TOC shortcode
- Numbered activity files with steps/challenge structure
- Answer key (optional) with per-activity solution blocks
- Empty media/ directory

Includes validation (kebab-case names, language dirs), dry-run
mode, and verbose output. Stdlib-only, no dependencies.

Co-authored-by: Copilot <[email protected]>
Per NF-QA-STANDARD.md TOC behavior section: workshops should use
alwaysopen: false to start with collapsed TOC sections.

Co-authored-by: Copilot <[email protected]>
Rewrite new-workshops.md from 3-line stub into comprehensive guide that
makes the scaffold script (tools/new-workshop.py) the mandatory first step
for creating new workshops. Add scaffold callout to getting-started.md.

Changes:
- new-workshops.md: full rewrite with scaffold as Step 1, options table,
  dry-run tip, content editing guide, local preview, PR workflow, and
  8-item pre-PR checklist (first item: used scaffold script)
- getting-started.md: add Creating a new workshop? section at bottom
  with scaffold command and link to new-workshops page

10-model QA + 3 clean convergence passes applied. Fixes from QA:
- Python 3.7+ prerequisite and python3 fallback note
- Distinct image paths for _index.md vs activity pages
- Kebab-case validation details (must start with letter)
- answer-key conditional language (if generated)
- Language folder note in git add step
- Mandatory scaffold framing (not optional)

Co-authored-by: Copilot <[email protected]>
@beagandica beagandica force-pushed the tools/workshop-scaffold branch from 66fb763 to bb0201e Compare April 29, 2026 02:11
beagandica pushed a commit to beagandica/workshops that referenced this pull request Apr 29, 2026
Merge comprehensive workshop creation guidance from WORKSHOP-STANDARDS.md
(PR NuevoFoundation#597) into the /guidelines/ pages so they are the one-stop shop for
contributors. PR NuevoFoundation#597 can now be closed.

new-workshops.md rewritten from 3-line stub to comprehensive guide:
- Workshop philosophy (story-driven, personalizable, self-paced, progressive)
- Gold standard examples (web-basics, python-turtle, earsketch)
- Scaffold script workflow (integrated from PR NuevoFoundation#634)
- Comprehensive quality checklist (36 items across 6 categories)
- PR review checklist (10 items for reviewers)
- Cross-links to all specialist guideline pages

Also updated:
- images-and-gifs.md: standardized on media/ convention (scaffold default),
  added backward-compat note for older workshops using img/,
  fixed shortcode delimiter consistency
- translation-volunteer.md: added Spanish tu-conjugation note
- _index.md: aligned all link texts with target page titles (sentence case)

10-model QA + 3 clean convergence passes.

Co-authored-by: Copilot <[email protected]>
ozhang22 pushed a commit that referenced this pull request May 6, 2026
…13) (#636)

* Add 5 missing guidelines pages (Closes #7, #10, #11, #12, #13)

New content pages for the contributor guidelines section:
- Translation volunteer guide (Closes #7)
- Images and GIFs (Closes #10)
- Navigation (Closes #11)
- Code and interactivity (Closes #12)
- Tags and metadata (Closes #13)

Updated _index.md to link all new pages and add a Translators section.

These issues have been open since July 2019. The content is based on
patterns established across 42 workshops and our NF QA standard.

Co-authored-by: Copilot <[email protected]>

* Fix QA findings: .NET Fiddle naming, CodePen pattern, Replit note, cross-refs

- Rename 'DotNetFiddle' to '.NET Fiddle' in prose (matching repo convention)
- Replace CodePen iframe embed with actual repo pattern (button link)
- Add note about replit.com vs old repl.it domain
- Note that raw HTML works without rawhtml shortcode (unsafe=true enabled)
- Add see-also cross-references to related guideline pages

Co-authored-by: Copilot <[email protected]>

* Fix QA pass 2 findings: icon table, details HTML, figure claim, Replit, notices

- H1: Remove broken icon shortcodes from table (theme incompatible), use text-only
- M1: Fix <details close> to <details> (valid HTML for collapsed state)
- M2: Remove 'preferred approach' claim for figure shortcode
- M3: Remove deprecated ?lite=true from Replit embed example
- M4: Use generic issue link (template PR not yet merged)
- M5: Fix notice shortcode delimiter from < > to % %

Co-authored-by: Copilot <[email protected]>

* Fold PR #597 workshop standards into guidelines pages

Merge comprehensive workshop creation guidance from WORKSHOP-STANDARDS.md
(PR #597) into the /guidelines/ pages so they are the one-stop shop for
contributors. PR #597 can now be closed.

new-workshops.md rewritten from 3-line stub to comprehensive guide:
- Workshop philosophy (story-driven, personalizable, self-paced, progressive)
- Gold standard examples (web-basics, python-turtle, earsketch)
- Scaffold script workflow (integrated from PR #634)
- Comprehensive quality checklist (36 items across 6 categories)
- PR review checklist (10 items for reviewers)
- Cross-links to all specialist guideline pages

Also updated:
- images-and-gifs.md: standardized on media/ convention (scaffold default),
  added backward-compat note for older workshops using img/,
  fixed shortcode delimiter consistency
- translation-volunteer.md: added Spanish tu-conjugation note
- _index.md: aligned all link texts with target page titles (sentence case)

10-model QA + 3 clean convergence passes.

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Beatris Mendez Gandica <[email protected]>
Co-authored-by: Copilot <[email protected]>
Documents the brand palette (emphasis #36374d, accents cyan/red/coral/
yellow/blush, plus neutrals) so contributors building visual workshops
(CSS demos, mini-games, diagrams) can stay on-brand without guessing.
References js-snack-picker as a real-world example.

Co-authored-by: Copilot <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant