Contribute an Interactive Learning Demo

This guide explains how to add a new interactive learning demo to the AI Outreach Platform.

Demos should run in the browser, work well in classroom settings, and be suitable for low-connectivity or offline use where possible.

They should also be compatible with the platform's offline release bundle used for classroom delivery.

How demo contributions work

Each demo has two parts:

An embeddable app in src/demos/<demo_id>/index.html.
A Markdown metadata page in src/learning/demos/<page-name>.md.

Folder structure

src/
├── demos/
│   └── <demo_id>/
│       ├── index.html
│       ├── style.css
│       ├── app.js
│       └── ...other assets
└── learning/
    └── demos/
        └── <page-name>.md

Required frontmatter

The metadata page is validated at build time. Required fields are:

demo_id
title
concept
tags
difficulty
author
description

demo_id must be unique and match the demo folder name.

Template

---
layout: layouts/base.njk
demo_id: your-demo-id
title: Your demo title
concept: short-ai-concept
tags:
  - one-tag
  - another-tag
difficulty: beginner
author: "Your name"
description: "One-sentence description of what the demo teaches."
permalink: "/learning/demos/your-demo/"
breadcrumbs:
  - label: Home
    url: "/"
  - label: Interactive Learning
    url: "/learning/"
  - label: Your demo title
---
{% include "partials/demo-page.njk" %}

Local preview and review

Run docker compose up --build and open http://localhost:8080.
Check that the demo appears on Interactive Learning.
Check that the embedded iframe loads and the page builds cleanly.
Open a pull request once the demo and metadata page are ready.

The site also ships as an offline release bundle for classroom use, so demos should avoid relying on external services for their core interaction.

For the full repo-level contributor guide, including offline expectations, see CONTRIBUTING.md in the project root.