Create Your First Codelab¶

This guide walks you through creating a complete codelab using all core features of Open Codelabs.

What is a codelab?¶

A codelab is a step-by-step learning guide. Each codelab:

Consists of multiple steps
Uses Markdown content
Can include code samples and images
Lets attendees proceed at their own pace

Step 1: Create a codelab¶

Access the admin dashboard¶

Log in at http://localhost:5173/login
Open the admin dashboard

Create a new codelab¶

Click "Create New Codelab" and enter the details:

Title: Build a REST API with Rust
Description: Create a RESTful API server using Axum
Author: Jane Doe

Writing a good title

Be clear and specific
Make the outcome obvious
Keep it concise (about 20-50 characters)

Step 2: Organize steps¶

Step structure design¶

A good codelab is organized into logical steps:

Overview - introduce what will be learned
Setup - install tools and dependencies
Core concepts - explain the theory
Practice - implement step by step
Testing - verify the result
Wrap-up - recap and next steps

Step 1: Overview¶

# Rust REST API Overview

## What will we build?

In this codelab, you will build a simple TODO REST API using Axum.

## What you will learn

- Axum basics
- RESTful API design principles
- SQLite integration
- Error handling

## Prerequisites

- Rust 1.75+
- Code editor (VS Code recommended)
- Terminal
- Postman or curl

## Estimated time

About 45 minutes

Step 2: Environment setup¶

# Environment Setup

## Create the project

Create a new Rust project:

```bash
cargo new todo-api
cd todo-api

Add dependencies¶

Open Cargo.toml and add the dependencies:

[dependencies]
axum = "0.7"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "sqlite"] }

Project structure¶

Create the following structure:

todo-api/
|-- Cargo.toml
|-- src/
|   |-- main.rs
|   |-- models.rs
|   `-- handlers.rs
`-- .env

Nice work

The setup is complete. Move to the next step.

### Step 3: Write the data models

```markdown
# Data Models

## Define the Todo struct

Create `src/models.rs` with the following code:

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Todo {
    pub id: i64,
    pub title: String,
    pub completed: bool,
}

#[derive(Debug, Deserialize)]
pub struct CreateTodo {
    pub title: String,
}

#[derive(Debug, Deserialize)]
pub struct UpdateTodo {
    pub title: Option<String>,
    pub completed: Option<bool>,
}

Code explanation¶

The Todo struct¶

id: unique identifier
title: task title
completed: completion flag

Serde derives¶

#[derive(Serialize, Deserialize)]: JSON serialization/deserialization
#[derive(Clone)]: allows cloning

Note

CreateTodo does not include id or completed. These are generated by the server.

## Step 3: Advanced Markdown features

### Code highlighting

You can highlight code blocks for different languages:

````markdown
```rust
fn main() {
    println!("Hello, world!");
}

console.log("Hello, world!");

print("Hello, world!")

````

Admonitions¶

You can highlight important information:

```markdown

Note

This is general information.

Tip

Useful advice goes here.

Warning

This requires caution.

Danger

This is critical.

Success

Success message.

Info

Additional info.

```

Tables¶

markdown | Method | Path | Description | |--------|------|-------------| | GET | /todos | List all todos | | GET | /todos/:id | Get a todo by id | | POST | /todos | Create a todo | | PUT | /todos/:id | Update a todo | | DELETE | /todos/:id | Delete a todo |

Links and images¶

```markdown

Rust Documentation

Architecture Diagram

Upload images in the admin UI to get a URL. ```

Lists¶

```markdown

Item 1
Item 2
Subitem 2.1
Subitem 2.2
Item 3

First step
Second step
Third step

[ ] Todo
[x] Done
[ ] Remaining ```

Step 4: Add images¶

Upload images¶

Click "Upload Image" in the step editor
Select a file (PNG, JPG, GIF)
Copy the generated URL
Insert into Markdown:

markdown ![Alt text](uploaded_image_url)

Resize images¶

Use HTML to control size:

html <img src="image_url" alt="Description" width="400"> <img src="image_url" alt="Description" style="width: 50%;">

Step 5: Manage attendees¶

Attendee codes¶

An attendee code is generated automatically when you create a codelab. Attendees enter it when joining.

Monitor attendees¶

In the admin dashboard:

View the attendee list in real time
Track each attendee's progress
Manage help requests

Handle help requests¶

When an attendee requests help:

A notification appears
Check which step they are stuck on
Provide help via 1:1 DM
Mark the issue as resolved

Step 6: Use real-time chat¶

Global chat¶

Communicate with all attendees:

[Facilitator]: We will move on in 5 minutes.

1:1 DM¶

Talk to a specific attendee:

Click the "DM" button next to the attendee name -> Send a private message

Step 7: Export and import¶

Export a codelab¶

Select a codelab in the admin dashboard
Click "Export"
Download the ZIP file

ZIP file structure:

codelab_xxx.zip |-- codelab.json # metadata |-- step_1.md # Step 1 content |-- step_2.md # Step 2 content `-- step_3.md # Step 3 content

Import a codelab¶

Click "Import"
Select the ZIP file
The codelab and steps are created automatically

Version control

Exporting a codelab makes it easy to version with Git.

Step 8: Collect feedback¶

When attendees complete a codelab, a feedback form is shown automatically:

Difficulty: 1-5
Satisfaction: 1-5
Comments: free-form

Admins can review all feedback in the dashboard.

Best practices¶

Content authoring¶

Cover only one concept per step
Keep code short and explanations clear
Focus on hands-on practice
Provide verification steps

Step length¶

Ideal step length: 5-10 minutes
Split overly long steps
End each step with a summary

Visual assets¶

Use diagrams for complex ideas
Include screenshots for results
Visualize architecture with diagrams

Error handling¶

Include common error cases
Provide clear resolutions
Add troubleshooting tips

Example template¶

A complete step template:

```markdown

[Step title]¶

Goal¶

In this step, you will learn [learning goal].

Concept¶

[Concept explanation]

Practice¶

1. [Sub-step title]¶

[Explanation]

[language] [code]

2. [Sub-step title]¶

[Explanation]

[language] [code]

Run¶

bash [command]

Expected output:

[output]

Verify¶

Check the following:

[ ] [Check item 1]
[ ] [Check item 2]
[ ] [Check item 3]

Success

Great job. Move to the next step.

Troubleshooting¶

Error: [error message]¶

Cause: [cause]

Fix: [solution]

Next step¶

In the next step, you will cover [next topic]. ```

Next steps¶

You learned how to create your first codelab. Continue with:

Public Deployment - expose locally via ngrok/bore/cloudflare
API Reference - automation and integrations
System Architecture - understand the platform

Need help?¶

FAQ - common questions
GitHub Issues - bug reports
Contributing - how to contribute