Skip to content

Add setup instructions and fix links to initial episodes #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johnwduggan merged 2 commits into from
Aug 13, 2026
Merged

Add setup instructions and fix links to initial episodes #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8dd7683
Fill in template data
johnwduggan Aug 12, 2026
f4db558
Add setup and fix links to episodes
johnwduggan Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,27 +33,27 @@ carpentry: "swc"
# dc-image: for Data Carpentry Image Processing
# swc-inflammation: for Software Carpentry based on the inflammation dataset
# swc-gapminder: for Software Carpentry based on the Gapminder dataset
curriculum: "FIXME"
curriculum: "swc-inflammation"

# If there is both an R and python official version of a curriculum
# (as listed on https://software-carpentry.org/lessons/ and
# https://datacarpentry.org/lessons/), change the
# value of the variable below ("flavor") to get the schedule and installation
# instructions updated accordingly (valid values are 'r' or 'python').
# Note: this is only for Data Carpentry and SWC at this time.
flavor: "FIXME"
flavor: "python"

# If the workshop will be a lesson pilot (for a new official lesson or
# a lesson in The Carpentries Incubator), set pilot to "true"
pilot: false
pilot: true

# Overall title for the Workshop.
# This variable is used to (optionally) add a title in the "jumbotron"
# (the grey box at the top of the page), and to the extra pages.
# Most workshops don't use extra pages. More information about extra
# pages are included in the README:
# https://github.com/carpentries/workshop-template#creating-extra-pages
title: "Workshop Title"
title: "Introduction to Web Development"

#------------------------------------------------------------
# Incubator workshop settings (only relevant for workshops teaching a lesson
Expand Down
0 _episodes/02-html_css_js.md → _episodes/01-html_css_js.md
View file
Open in desktop
File renamed without changes.
0 _episodes/03-next_quickstart.md → _episodes/02-next_quickstart.md
View file
Open in desktop
File renamed without changes.
Empty file added _includes/swc/custom_schedule.html
View file
Open in desktop
Empty file.
145 changes: 14 additions & 131 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@ layout: workshop # DON'T CHANGE THIS.
# More detailed instructions (including how to fill these variables for an
# online workshop) are available at
# https://carpentries.github.io/workshop-template/customization/index.html
venue: "FIXME" # brief name of the institution that hosts the workshop without address (e.g., "Euphoric State University")
address: "FIXME" # full street address of workshop (e.g., "Room A, 123 Forth Street, Blimingen, Euphoria"), videoconferencing URL, or 'online'
country: "FIXME" # lowercase two-letter ISO country code such as "fr" (see https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) for the institution that hosts the workshop
language: "FIXME" # lowercase two-letter ISO language code such as "fr" (see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for the workshop
latitude: "45" # decimal latitude of workshop venue (use https://www.latlong.net/)
longitude: "-1" # decimal longitude of the workshop venue (use https://www.latlong.net)
humandate: "FIXME" # human-readable dates for the workshop (e.g., "Feb 17-18, 2020")
humantime: "FIXME" # human-readable times for the workshop e.g., "9:00 am - 4:30 pm CEST (7:00 am - 2:30 pm UTC)"
startdate: FIXME # machine-readable start date for the workshop in YYYY-MM-DD format like 2015-01-01
enddate: FIXME # machine-readable end date for the workshop in YYYY-MM-DD format like 2015-01-02
instructor: ["instructor one", "instructor two"] # boxed, comma-separated list of instructors' names as strings, like ["Kay McNulty", "Betty Jennings", "Betty Snyder"]
helper: ["helper one", "helper two"] # boxed, comma-separated list of helpers' names, like ["Marlyn Wescoff", "Fran Bilas", "Ruth Lichterman"]
email: ["first@example.org","second@example.org"] # boxed, comma-separated list of contact email addresses for the host, lead instructor, or whoever else is handling questions, like ["marlyn.wescoff@example.org", "fran.bilas@example.org", "ruth.lichterman@example.org"]
venue: "Oak Ridge National Laboratory" # brief name of the institution that hosts the workshop without address (e.g., "Euphoric State University")
address: "Bldg 5100, Conference Rm 140, Oak Ridge, TN" # full street address of workshop (e.g., "Room A, 123 Forth Street, Blimingen, Euphoria"), videoconferencing URL, or 'online'
country: "us" # lowercase two-letter ISO country code such as "fr" (see https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) for the institution that hosts the workshop
language: "en" # lowercase two-letter ISO language code such as "fr" (see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for the workshop
latitude: "36.012009" # decimal latitude of workshop venue (use https://www.latlong.net/)
longitude: "-84.265533" # decimal longitude of the workshop venue (use https://www.latlong.net)
humandate: "August 17th, 2026" # human-readable dates for the workshop (e.g., "Feb 17-18, 2020")
humantime: "11:00 am - 12:00 pm EDT" # human-readable times for the workshop e.g., "9:00 am - 4:30 pm CEST (7:00 am - 2:30 pm UTC)"
startdate: 2026-08-17 # machine-readable start date for the workshop in YYYY-MM-DD format like 2015-01-01
enddate: 2026-08-17 # machine-readable end date for the workshop in YYYY-MM-DD format like 2015-01-02
instructor: ["John Duggan", "Greg Cage"] # boxed, comma-separated list of instructors' names as strings, like ["Kay McNulty", "Betty Jennings", "Betty Snyder"]
helper: [] # boxed, comma-separated list of helpers' names, like ["Marlyn Wescoff", "Fran Bilas", "Ruth Lichterman"]
email: ["dugganjw@ornl.gov","cagege@ornl.gov"] # boxed, comma-separated list of contact email addresses for the host, lead instructor, or whoever else is handling questions, like ["marlyn.wescoff@example.org", "fran.bilas@example.org", "ruth.lichterman@example.org"]
collaborative_notes: # optional: URL for the workshop collaborative notes, e.g. an Etherpad or Google Docs document (e.g., https://pad.carpentries.org/2015-01-01-euphoria)
eventbrite: # optional: alphanumeric key for Eventbrite registration, e.g., "1234567890AB" (if Eventbrite is being used)
what3words: # optional: what3words (https://what3words.com) address of the workshop venue, without leading slashes e.g. "globe.lessening.computers"
Expand All @@ -39,22 +39,6 @@ And run 'make workshop-check' *before* committing to make sure that changes are
For a workshop please delete the following block until the next dashed-line
{% endcomment %}


<div class="alert alert-danger">
This is the workshop template. Delete these lines and use it to
<a href="https://carpentries.github.io/workshop-template/customization/index.html">customize</a>
your own website. If you are running a self-organized workshop or have not put
in a workshop request yet, please also fill in
<a href="{{site.amy_site}}/forms/self-organised/">this workshop request form</a>
to let us know about your workshop and our administrator may contact you if we
need any extra information.
If this is a pilot workshop for a new lesson,
set the `pilot` field to `true` in `_config.yml`.
For workshops teaching a lesson in The Carpentries Incubator,
remember to uncomment the `incubator_lesson_site`, `incubator_pre_survey`, and `incubator_post_survey`
fields in `_config.yml`
</div>

{% comment %}
8< ============================= until here ==================
{% endcomment %}
Expand Down Expand Up @@ -367,31 +351,6 @@ We will use this <a href="{{ page.collaborative_notes }}">collaborative document
{% endif %}


{% comment %}
SURVEYS - DO NOT EDIT SURVEY LINKS
{% endcomment %}
<h2 id="surveys">Surveys</h2>
<p>Please be sure to complete these surveys before and after the workshop.</p>
{% if site.carpentry == "incubator" %}
<p><a href="{{ site.incubator_pre_survey }}">Pre-workshop Survey</a></p>
<p><a href="{{ site.incubator_post_survey }}">Post-workshop Survey</a></p>
{% elsif site.incubator_pre_survey or site.incubator_post_survey %}
<div class="alert alert-danger">
WARNING: you have defined custom pre- and/or post-survey links for
a workshop not configured for The Carpentries Incubator
(the value of `curriculum` is not set to `incubator` in `_config.yml`).
Please comment out the `incubator_pre_survey` and `incubator_post_survey` fields
in `_config.yml` or, if this workshop is teaching a lesson in the Incubator,
change the value of `carpentry` to `incubator`.
</div>
{% else %}
<p><a href="{{ site.pre_survey }}{{ site.github.project_title }}">Pre-workshop Survey</a></p>
<p><a href="{{ site.post_survey }}{{ site.github.project_title }}">Post-workshop Survey</a></p>
{% endif %}

<hr/>


{% comment %}
SCHEDULE

Expand All @@ -414,19 +373,6 @@ of code below the Schedule `<h2>` header below with
`{% include custom-schedule.html %}`.
{% endcomment %}

<h2 id="schedule">Schedule</h2>

{% if site.carpentry == "swc" %}
{% include swc/schedule.html %}
{% elsif site.carpentry == "dc" %}
{% include dc/schedule.html %}
{% elsif site.carpentry == "lc" %}
{% include lc/schedule.html %}
{% elsif site.carpentry == "incubator" %}
This workshop is teaching a lesson in
<a href="https://carpentries-incubator.org/">The Carpentries Incubator</a>. Please check <a href="{{site.incubator_lesson_site}}">the lesson homepage</a> for a list of lesson sections and estimated timings.
{% endif %}

{% comment %}
Edit/replace the text above if you want to include a schedule table.
See the contents of the _includes/custom-schedule.html file for an example of
Expand All @@ -439,67 +385,4 @@ The lesson taught in this workshop is being piloted and a precise schedule is ye

<hr/>


{% comment %}
SETUP

Delete irrelevant sections from the setup instructions. Each
section is inside a 'div' without any classes to make the beginning
and end easier to find.

This is the other place where people frequently make mistakes, so
please preview your site before committing, and make sure to run
'tools/check' as well.
{% endcomment %}

<h2 id="setup">Setup</h2>

<p>
To participate in a
{% if site.carpentry == "swc" %}
Software Carpentry
{% elsif site.carpentry == "dc" %}
Data Carpentry
{% elsif site.carpentry == "lc" %}
Library Carpentry
{% endif %}
workshop,
you will need access to software as described below.
In addition, you will need an up-to-date web browser.
</p>
<p>
We maintain a list of common issues that occur during installation as a reference for instructors
that may be useful on the
<a href = "{{site.swc_github}}/workshop-template/wiki/Configuration-Problems-and-Solutions">Configuration Problems and Solutions wiki page</a>.
</p>

{% comment %}
For online workshops, the section below provides:
- installation instructions for the Zoom client
- recommendations for setting up Learners' workspace so they can follow along
the instructions and the videoconferencing

If you do not use Zoom for your online workshop, edit the file
`_includes/install_instructions/videoconferencing.html`
to include the relevant installation instructions.
{% endcomment %}
{% if online != "false" %}
{% include install_instructions/videoconferencing.html %}
{% endif %}

{% comment %}
These are the installation instructions for the tools used
during the workshop.
{% endcomment %}

{% if site.carpentry == "swc" %}
{% include swc/setup.html %}
{% elsif site.carpentry == "dc" %}
{% include dc/setup.html %}
{% elsif site.carpentry == "lc" %}
{% include lc/setup.html %}
{% elsif site.carpentry == "incubator" %}
Please check the "Setup" page of
<a href="{{site.incubator_lesson_site}}">the lesson homepage</a> for instructions to follow
to obtain the software and data you will need to follow the lesson.
{% endif %}
<h2 id="setup-link"><a href="/setup/index.html">Setup</a></h2>
75 changes: 25 additions & 50 deletions setup/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,65 +1,40 @@
---
layout: page
title: Testing Setup
title: Setup
root: ..
---

This directory contains scripts for testing your machine to make sure
you have the software you'll need for your workshop installed. To use
these scripts:
# Prerequisites

1. Download [swc-installation-test-1.py](swc-installation-test-1.py).
This lesson assumes you have a fundamental understanding of working with the UNIX shell. If you don't, then we recommend you use the
[The Unix Shell lesson](https://swcarpentry.github.io/shell-novice/) provided by Software Carpentry before beginning this material.

2. Run it from the shell:
# Required Software

~~~
$ python swc-installation-test-1.py
Passed
~~~
This lesson requires you to install [Pixi](https://pixi.prefix.dev/latest/) and [Node.js](https://nodejs.org/en) to get started. While

@gecage952 gecage952 Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, we're using pixi here?

@gecage952 gecage952 Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the backend, I guess? I don't mind, necessarily, but I would say if we're not doing anything that would include ex-conda stuff, I think uv would be more familiar to people.

Edit: If you think most people there will be familiar with pixi, then just ignore this comment.

@gecage952 gecage952 Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also should add pnpm as a requirement here.

@johnwduggan johnwduggan Aug 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with switching to uv. Let me make that change here.

not necessary, it's also recommended that you have an IDE such as [VSCode](https://code.visualstudio.com/) installed for modifying the
files used in this lesson.

3. Download [swc-installation-test-2.py](swc-installation-test-2.py).
However you install the software, once done you should be able to run the following commands:

4. Run it from the shell:
```command
pixi --version
```

~~~
$ python swc-installation-test-2.py
check virtual-shell... pass
...
Successes:
```output
pixi 0.62.2
```

virtual-shell Bourne Again Shell (bash) 4.2.37
...
~~~
```command
node --version
npm --version
```

If you see something like:
```output
v24.12.0
11.6.2
```

~~~
$ python swc-installation-test-2.py
check virtual-shell... fail
...
check for command line shell (virtual-shell) failed:
command line shell (virtual-shell) requires at least one of the following dependencies
For instructions on installing an up-to-date version, see
http://software-carpentry.org/setup/
causes:
check for Bourne Again Shell (bash) failed:
could not find 'bash' executable for Bourne Again Shell (bash)
For instructions on installing an up-to-date version, see
http://software-carpentry.org/setup/
...
~~~
You may see slightly different versions, but these are generally unlikely to cause issues following the lesson materials.

follow the suggestions to try and install any missing software. For
additional troubleshooting information, you can use the `--verbose`
option:

~~~
$ python swc-installation-test-2.py --verbose
check virtual-shell... fail
...
==================
System information
==================
os.name : posix
...
~~~
{% include links.md %}
Loading