All in One View

Content from Building Your Own Carpentries Lesson

Last updated on 2026-06-29 | Edit this page

Estimated time: 75 minutes

Overview

Questions

  • What is Markdown and how do I use it to write lesson content?
  • How do I create a Carpentries-style lesson website using the Workbench template?
  • How do I add and organize episodes in my lesson?
  • How do I work on my lesson locally using GitHub Desktop?

Objectives

  • Write formatted text, headings, lists, links, and images using Markdown
  • Create a Carpentries lesson repository from the official template
  • Clone the repository locally using GitHub Desktop
  • Add episodes and configure the lesson structure
  • Understand the Carpentries Workbench file layout

Introduction

This morning you designed a geospatial teaching module — you identified a spatial problem, the data it requires, and where to find that data. Now you will build it as a Carpentries-style lesson website, hosted for free on GitHub Pages.

We will start with Markdown basics (the language Carpentries lessons are written in), then walk through creating and customizing a lesson repository.

Prerequisites:

Part 1: Markdown Basics

All Carpentries lesson content is written in Markdown — a lightweight text format that converts to HTML automatically. You do not need to know HTML. Markdown is designed to be readable as plain text and simple to learn.

Headings

MARKDOWN 

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use headings to structure your episodes into sections. In Carpentries lessons, ## is the standard section heading.

Text Formatting

MARKDOWN 

**Bold text**
*Italic text*
`Inline code`

MARKDOWN 

[Link text](https://example.com)

![Alt text describing the image](image.png "Optional title")

Note: The image has to be in the same folder where your episodes/modules exist. More on the episodes folder below.

Lists

MARKDOWN 

Bulleted list:
- Item one
- Item two
- Item three

Numbered list:
1. First step
2. Second step
3. Third step

Code Blocks

Use triple backticks with an optional language name for syntax highlighting:

MARKDOWN 

```python
import pandas as pd
df = pd.read_csv("data.csv")
```

Tables

MARKDOWN 

| Column A | Column B | Column C |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Carpentries-Specific Blocks

The Carpentries Workbench adds special fenced blocks for pedagogical elements:

MARKDOWN 

::::::::::::::::::::::::::::::::::::: callout

### Tip
This is a callout box for important notes or tips.

::::::::::::::::::::::::::::::::::::::::::::::::

MARKDOWN 

:::::::::::::::::::::::::::::::::::: challenge

### Exercise Title
Write the exercise prompt here.

::::::::::::::::::::::::::::::::::::::::::::::::

MARKDOWN 

::::::::::::::::::::::::::::::::::::: keypoints

- First key takeaway
- Second key takeaway

::::::::::::::::::::::::::::::::::::::::::::::::

Other available block types include questions, objectives, discussion, and solution.

Callout

Quick Reference

For a full Markdown guide, see markdownguide.org. For Carpentries-specific formatting, see the Workbench documentation.

Part 2: Create Your Lesson Repository

The Carpentries provides an official template called the Workbench that generates a professional lesson website automatically from your Markdown files. You do not need to write any HTML or CSS.

Step 1: Use the Template

Important: Do not fork the repository — use GitHub’s “Use this template” feature instead.

  1. Go to the Carpentries Workbench template: https://github.com/carpentries/workbench-template-md

  2. Click the green Use this template button (top right) → Create a new repository

  3. Fill in the details:

    • Owner: your GitHub username or organization
    • Repository name: use the Carpentries naming convention — YYYY-MM-DD-sitename-topicname (e.g., 2026-06-30-purdue-geospatial)
    • Keep Include all the branches on
    • Visibility: Public (required for GitHub Pages to work)

  4. Click Create repository

Your lesson website will be built automatically and available at: https://yourusername.github.io/your-repo-name/

In this case:

  1. yourusername - This is your GitHub username.
  2. your-repo-name - This is your repo name. From the example above 2026-06-30-purdue-geospatial.

It may take a couple of minutes for the first build to complete.

Callout

Tip

If you forget the naming convention, your site will still work — but using the YYYY-MM-DD-sitename format helps The Carpentries community index and discover your workshop.

Part 3: Work Locally with GitHub Desktop

Editing files directly on GitHub works for small changes, but for building a full lesson it is much easier to work locally on your computer. GitHub Desktop lets you do this without using the command line.

Step 1: Clone Your Repository

  1. Open GitHub Desktop and log in with your GitHub account.
  2. Click File → Clone Repository.
  3. Find the lesson repository you just created and choose a local path (e.g., your Desktop).
  4. Click Clone.

You now have a local folder with all the lesson files. Any changes you make to files in this folder will appear in GitHub Desktop.

Step 2: Edit, Commit, and Push

The workflow is:

  1. Edit files in your local folder using any text editor (VS Code, Notepad++, or even plain Notepad)
  2. Save the files
  3. Open GitHub Desktop — you will see your changes listed
  4. Write a short summary describing what you changed (this is required)
  5. Click Commit to main
  6. Click Push origin in the top right to send your changes to GitHub

Your lesson website will rebuild automatically after each push.

Staying in Sync

If you make changes on GitHub through a browser (or a collaborator pushes changes), click Fetch origin in GitHub Desktop before editing locally. This pulls the latest version so you do not create conflicts.

Part 4: Understanding the Lesson Structure

Your cloned folder contains several important files and folders:

your-lesson/
├── config.yaml          ← lesson title, description, episode order
├── episodes/
│   └── introduction.md  ← your first episode (lesson page)
├── instructors/         ← instructor-only notes
├── learners/
│   └── setup.md         ← setup instructions for students
└── profiles/            ← learner profiles

The config.yaml File

This file controls your lesson’s title, description, and the order in which episodes appear. Open it in a text editor and look for the episodes section (around line 67):

YAML 

episodes:
- introduction.md

To add more episodes, list them here in the order you want them to appear:

YAML 

episodes:
- introduction.md
- data-collection.md
- analysis.md
- visualization.md

The episodes/ Folder

Each .md file in this folder becomes one page (episode) in your lesson website. The file you worked with throughout this workshop — with its YAML header, questions, objectives, content, and keypoints — is exactly what goes here.

The learners/setup.md File

This is where setup instructions for students go — software to install, accounts to create, and data to download. The setup page we built on Day 1 of this workshop is an example of this file.

Part 5: Add Your First Episode

Now you will turn the geospatial module you designed this morning into a Carpentries episode.

Step 1: Create the File

In your local episodes/ folder, create a new file with a descriptive name (e.g., urban-heat-analysis.md). Start with the standard Carpentries header:

MARKDOWN 

---
title: "Your Episode Title"
teaching: 30
exercises: 15
---

:::::::::::::::::::::::::::::::::::::: questions

- First question your episode addresses
- Second question

::::::::::::::::::::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::::::: objectives

- First learning objective
- Second learning objective

::::::::::::::::::::::::::::::::::::::::::::::::

## Section 1

Your content here — explanations, instructions, code blocks, images.

:::::::::::::::::::::::::::::::::::: challenge

### Exercise Title

Exercise instructions here.

::::::::::::::::::::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::::::: keypoints

- First key takeaway
- Second key takeaway

::::::::::::::::::::::::::::::::::::::::::::::::

Step 2: Register It in config.yaml

Open config.yaml and add your new file name to the episodes list:

YAML 

episodes:
- introduction.md
- urban-heat-analysis.md

Step 3: Commit and Push

  1. Save both files
  2. In GitHub Desktop, write a commit summary (e.g., “Add urban heat episode”)
  3. Click Commit to main, then Push origin
  4. Wait a few minutes, then check your lesson website — your new episode should appear in the navigation
Discussion

Exercise: Build Your Module

Using the geospatial teaching element you designed this morning, create a Carpentries episode:

  1. Create a new .md file in your episodes/ folder
  2. Add the YAML header with title, teaching time, and exercise time
  3. Write at least a questions block, an objectives block, one content section with a heading, and a keypoints block
  4. Add the file to config.yaml
  5. Commit and push
  6. Verify that your episode appears on your lesson website

If time allows, add a second section, an exercise block, or a callout.

Reference: Example Lesson Repository

To see a completed example of a multi-episode Carpentries lesson built using this workflow, see the Data Analysis module we created: github.com/SpatialTurn/DataAnalysis. Pay attention to the episodes/ folder and the config.yaml file to see how episodes are organized.

You can also use the template we created at github.com/SpatialTurn/carpentrytemp.github.io as a starting point for a custom landing page for your workshop.

Key Points
  • Markdown is the language used to write Carpentries lesson content — it is plain text with simple formatting rules.
  • The Carpentries Workbench template generates a professional lesson website automatically from your Markdown files.
  • Each episode is a single .md file in the episodes/ folder; the config.yaml file controls which episodes appear and in what order.
  • GitHub Desktop lets you edit lesson files locally and push changes without using the command line.

Content from Additional Readings

Last updated on 2026-06-25 | Edit this page

Estimated time: 40 minutes

Overview

Questions

  • What is data curation and why does it matter for research?
  • What practical steps can I take to keep my data organized and reusable?
  • What are the FAIR principles?
  • How do I publish and share research data at scale?

Objectives

  • Understand the purpose and lifecycle of data curation
  • Apply practical organization, naming, and documentation standards to research data
  • Describe the FAIR principles and why they matter for reproducibility
  • Know how to use institutional repositories (PURR) and data transfer tools (Globus) to publish and share data

What Is Data Curation?

Data curation is the process of organizing, documenting, preserving, and maintaining data so that it remains useful, understandable, and reusable over time. It is not just storing files — it is making data usable for future analysis, whether by you, your collaborators, or researchers you have never met.

Poorly curated data leads to lost files, confusing variable names, missing context, and irreproducible results. Well-curated data saves time, prevents mistakes, enables collaboration, and makes research reproducible.

Consider the difference:

  • final_data_v2_revised_REAL_final.csv — tells you almost nothing
  • soil_moisture_2025_stationA_clean.csv — tells you the variable, year, location, and processing stage

Curation begins when data is created, not after the project ends.

The Data Curation Lifecycle

Data curation is not a one-time task. It happens throughout the life of a dataset:

  1. Create / Collect — data is generated from instruments, surveys, fieldwork, APIs, or computational models
  2. Organize — files are structured into a logical folder hierarchy
  3. Document — metadata and README files are written to explain what the data contains
  4. Store / Backup — data is saved redundantly across multiple locations
  5. Preserve — data is archived in stable, open formats for long-term access
  6. Share / Publish — data is deposited in a repository and assigned a permanent identifier
  7. Reuse / Reanalyze — others discover, cite, and build on the data

For small projects this cycle may happen on a single laptop. For large collaborative projects it may span multiple institutions, countries, and automated pipelines. The principles are the same — the infrastructure scales.

Practical Data Organization

Folder Structure

A clear folder hierarchy makes it easy to find files and reproduce your workflow. A common pattern:

project/
├── data_raw/        ← original, untouched data
├── data_clean/      ← processed and analysis-ready data
├── scripts/         ← code that transforms raw → clean
├── outputs/         ← figures, maps, tables
└── documentation/   ← README, metadata, data dictionary

Write your scripts so that they read from data_raw/ and save results to outputs/. This way you can always reproduce the full workflow from the original data.

Naming Conventions

Good file names are descriptive, consistent, and machine-readable:

  • river_discharge_monthly_2024.csv — clear
  • data_new_latest2.csv — unclear

Avoid spaces, special characters, and ambiguous version labels. Use dates in YYYY-MM-DD format so files sort chronologically.

Documentation

Every dataset should include a README file that covers:

  • Project title and author
  • Date created and last updated
  • Description of each file
  • Variable names and units of measurement
  • Data source and collection method
  • Any known limitations or gaps

The README is the single most important piece of documentation you can write. If someone finds your dataset five years from now, the README is what makes it usable or useless.

Metadata

Metadata is “data about data” — structured information that describes what a dataset contains, how it was collected, and what the fields mean. Good metadata answers: who created it, when, with what instruments, and what do the columns represent?

For geospatial data, metadata also includes the coordinate reference system, spatial extent, and resolution.

File Formats

Choose formats that are open, widely supported, and non-proprietary whenever possible:

  • CSV over XLSX for tabular data
  • GeoJSON or GeoPackage over proprietary GIS formats
  • GeoTIFF for raster data (already georeferenced and widely supported)
  • Plain text (TXT, MD) over DOCX for documentation

Open formats ensure your data remains readable regardless of which software is available in the future.

Version Control

Track changes to your data and code over time. Two complementary approaches:

  • Version numbering for data files — survey_cleaned_v1.csv, survey_cleaned_v2.csv, with a changelog documenting what changed between versions
  • Git / GitHub for code and documentation — tracks every change with a full history
Callout

Never Overwrite Raw Data

Keep your original raw data unchanged in data_raw/. All cleaning and transformation should produce new files in data_clean/. If something goes wrong, you can always start over from the original.

Backup: The 3-2-1 Rule

  • 3 copies of your data
  • 2 different storage types (e.g., local drive + cloud)
  • 1 offsite backup

For example: your laptop, an external hard drive, and a cloud service. If any one fails, you still have two copies.

FAIR Principles

The FAIR framework is the widely adopted standard for research data management. Curated data should be:

  • Findable — stored in a searchable repository with a persistent identifier (like a DOI)
  • Accessible — available to authorized users through standard protocols
  • Interoperable — uses open formats and standard vocabularies so it works with other tools and datasets
  • Reusable — documented thoroughly enough that someone else can understand and use it without contacting you

FAIR does not mean all data must be public — it means data should be as open as possible and as closed as necessary, with clear access conditions.

Publishing Data: Institutional Repositories

When curated data is deposited into a repository, it receives a permanent identifier, becomes discoverable worldwide, and can be cited in publications just like a journal article.

PURR (Purdue University Research Repository)

PURR is Purdue University’s platform for publishing and preserving research data. It allows researchers to:

  • Store curated datasets securely
  • Assign DOIs (Digital Object Identifiers) so others can cite the data
  • Share data publicly or with restricted access
  • Meet data management requirements from funding agencies and journals

Repositories like PURR protect data from loss and make it reusable beyond the original project. Many universities and funding agencies now require a data management plan that includes repository deposit.

Sharing Large Datasets: Globus

Some datasets — satellite imagery archives, climate model simulations, high-resolution remote sensing data — are too large for email, USB drives, or standard cloud sharing. These require dedicated transfer infrastructure.

What Is Globus?

Globus is a research data transfer platform widely used in academia. It supports:

  • Secure, high-volume transfers (terabytes between institutions)
  • Automatic retry and verification (no babysitting long transfers)
  • Scheduled and automated workflows
  • Transfers between institutional HPC clusters, cloud storage, and personal machines

For example, a researcher in Indiana can transfer 5 TB of satellite data to collaborators in Europe reliably and securely, without worrying about interrupted connections or corrupted files.

Ethics and Privacy

Research data often contains sensitive information. Before sharing:

  • Remove personal identifiers from survey and demographic data
  • Follow your institution’s IRB (Institutional Review Board) guidelines
  • Respect licensing restrictions on data you did not collect yourself
  • Consider aggregation levels carefully for geospatial data — fine-grained location data can expose individuals even when names are removed
Discussion

Exercise: Curate a Sample Project

Create a folder structure for a hypothetical research project on urban heat islands in your city. Include:

  1. A data_raw/ folder (what files would go here?)
  2. A data_clean/ folder
  3. A scripts/ folder
  4. A documentation/ folder containing a brief README (3–5 sentences describing the project, data sources, and key variables)

If time allows, discuss with a partner: what metadata would someone need to reuse your dataset five years from now?

Key Points
  • Data curation is an ongoing process that begins when data is created, not after a project ends.
  • Practical habits — clear folder structures, descriptive file names, README files, and open formats — are the foundation of good curation.
  • The FAIR principles (Findable, Accessible, Interoperable, Reusable) are the standard framework for research data management.
  • Institutional repositories like PURR provide permanent, citable homes for research data.
  • Large-scale data sharing relies on tools like Globus that handle high-volume transfers reliably.