Skip to content

Commit c730352

Browse files
adevroy569adevroy569
committed
added carpentry introduction
1 parent e79575d commit c730352

2 files changed

Lines changed: 168 additions & 0 deletions

File tree

‎config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ contact: 'team@carpentries.org' # FIXME
6767
# Order of episodes in your lesson
6868
episodes:
6969
- introduction.md
70+
- carpentry.md
7071

7172
# Information for Learners
7273
learners:

‎episodes/carpentry.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: "How to Create Your Own Carpentries-Style Workshop Website Using GitHub"
3+
teaching: 40
4+
exercises: 20
5+
---
6+
7+
# How to Create Your Own Carpentries-Style Workshop Website Using GitHub
8+
9+
**A beginner-friendly guide for instructors, lesson authors, and community members**
10+
11+
After this lesson you will be able to:
12+
13+
- Create a professional-looking workshop website using The Carpentries template
14+
- Host it for free on GitHub Pages
15+
- Customize key information (dates, instructors, setup instructions)
16+
- Understand why we avoid forking and use the template instead
17+
18+
**Target audience**: Anyone planning a Carpentries-style workshop (Software, Data, Library Carpentry) who has a basic GitHub account.
19+
20+
**Prerequisites**:
21+
- A free GitHub account (sign up at github.com if you don't have one)
22+
- A web browser
23+
- (Optional but recommended) Basic familiarity with Markdown
24+
25+
---
26+
27+
## Why Use The Carpentries Workshop Template?
28+
29+
The Carpentries provides a ready-made template that:
30+
31+
- Looks professional and consistent with hundreds of Carpentries workshops
32+
- Automatically generates schedule, setup, FAQ, and other standard pages
33+
- Is mobile-friendly
34+
- Is hosted for free via **GitHub Pages**
35+
- Supports easy customization via one main file (`_config.yml`)
36+
37+
There are two main Carpentries website types:
38+
39+
- **Workshop websites** → short-term event pages (what this guide covers)
40+
- **Lesson websites** → long-term curriculum pages (uses The Carpentries Workbench — see notes at end)
41+
42+
---
43+
44+
## Step 1: Create Your Repository from the Template
45+
46+
**Important**: Do **NOT** fork the repository — use GitHub's "Use this template" feature instead.
47+
48+
1. Go to:
49+
https://github.com/carpentries/workshop-template
50+
51+
2. Click the green **Use this template** button (top right) → **Create a new repository**
52+
53+
3. Fill in the details:
54+
- **Owner**: your GitHub username or an organization
55+
- **Repository name**: Use the Carpentries naming convention:
56+
`YYYY-MM-DD-sitename-lessonname`
57+
Example: `2026-05-15-purdue-python-novice`
58+
- Description (optional): "Python for Beginners – May 2026, Purdue University"
59+
- Visibility: **Public** (required for GitHub Pages)
60+
61+
4. Click **Create repository**
62+
63+
> **Tip**: If you forget the naming convention, your site will still work — but using the slug format helps The Carpentries index your workshop.
64+
65+
---
66+
67+
## Step 2: Install GitHub Desktop.
68+
69+
1. After installation, login to the application.
70+
71+
2. Click on `File` then `Clone Repository` on the top left.
72+
73+
3. Find the newly created repository and save it locally on your desktop.
74+
75+
4. Go the folder which has the cloned repository.
76+
77+
5. Any change you make in this folder will reflect on the GitHub desktop application. Make sure to **save** the changes.
78+
79+
6. After making the changes, add a summary (this is required), and then `Push` on the top right of the application.
80+
81+
That's it! Now you can make changes locally to your webpage without having to open GitHub in a browser.
82+
83+
**Tip:** If you happen to make changes to the webpage repository from a browser and to make sure you have saved the progress locally in your desktop, all you have to do is `Fetch Origin` in the top right of the application to update your local folder repo of the changes.
84+
85+
## Step 3: Enable GitHub Pages - Create another repository
86+
87+
GitHub Pages builds and hosts your site automatically from the `gh-pages` branch.
88+
89+
1. In your new repository, go to **Settings** (top tab)
90+
91+
2. Scroll down to **Pages** (in the left sidebar, under "Code and automation")
92+
93+
3. Under **Source**:
94+
- Branch: select `gh-pages`
95+
- Folder: select `/ (root)`
96+
- Click **Save**
97+
98+
4. Wait 1–2 minutes, then refresh.
99+
GitHub will show:
100+
"Your site is live at https://**your-username**.github.io/**your-repo-name**/"
101+
102+
Copy this URL — that's your website!
103+
104+
5. In our case, we have a repository/webpage name called `spatialturn.github.io`. See [here](https://github.com/SpatialTurn).
105+
106+
---
107+
108+
## Step 4: Edit the Main Configuration File (`_config.yml`)
109+
110+
This single file controls almost everything.
111+
112+
1. In your repository, open the file called `_config.yml`
113+
114+
2. Edit these key fields (use the pencil icon → commit changes):
115+
116+
```yaml
117+
# --- general ---
118+
title: "Python for Novices" # Workshop title
119+
life_cycle: "upcoming" # or past/current
120+
carpentry: "dc" # dc = Data Carpentry, swc = Software, lc = Library
121+
country: "us" # two-letter code
122+
country-full: "United States"
123+
city: "West Lafayette"
124+
venue: "Purdue University, Wilmeth Active Learning Center"
125+
address: "155 S Grant St, West Lafayette, IN 47907"
126+
contact: "instructor@purdue.edu"
127+
handout: "" # optional link to Etherpad/Google Doc
128+
eventbrite: "" # optional registration link
129+
130+
# --- dates ---
131+
start_date: "2026-05-15"
132+
end_date: "2026-05-16"
133+
134+
# --- instructors/helpers ---
135+
instructor:
136+
- Jane Doe
137+
helper:
138+
- Helper Name One
139+
- Helper Name Two
140+
141+
# --- links ---
142+
website: "" # leave blank — GitHub fills it
143+
144+
145+
3. Create a file called `index.html` or whatever name you prefer. This will be the place where you make changes to your webpage.
146+
147+
---
148+
149+
## Final Step - Adding Content to Webpage.
150+
151+
152+
1. Open the folder called episodes in repository created using the carpentry template in Step 1.
153+
154+
2. You should see a file called `introduction.md`.
155+
156+
3. This is the file where you can add content for a specific module.
157+
158+
4. You can always add newer modules by adding newer .md or markdown files within the episodes folder.
159+
160+
5. Make sure to add that particular file name in `config.yaml` file and save it. It is usually around line 67.
161+
162+
6. By default `config.yaml` has only `introduction.md` but you can more to that if you decide to add more content to it.
163+
164+
7. Check the changes we made when we created our webpages for the Data Analysis module [here](https://github.com/SpatialTurn/DataAnalysis).
165+
166+
**Tip:** See the changes we made to `episodes` folder and `config.yaml` file.
167+

0 commit comments

Comments
 (0)