Creating a JupyterLite Server for the classroom

Set up
Changing content
Common errors
1. After creating the repository, I only see a static site like…
2. Missing features

Set up

Navigate to Titus’ template
- https://github.com/ctb/2025-jupyterlite-template
In the upper right, click Use this template > Create a new repository
The repository name will be the path of the URL. I.e. if you name a repo stats102 and your username is spartacus, the URL will be spartacus.github.io/stats102.
Repositories may also be public or private. Private repositories may require an upgraded subscription. Look into signing up for GitHub for Teachers to bypass a subscription fee.
Add a Repository name and click Create repository to generate a public repository hosting a JupyterLite session for your courses/curriculum.
This new repository will be fully set up and attempts to run a GitHub Action, or a set of commands that will help build the JupyterLite session.
This GitHub Action may fail, showing a red ‘X’ instead of the green check for a successful run.
Enable GitHub Pages to create the website from your repositories files for your JupyterLite session.
a. Go to the Settings tab on the upper right
b. Under General > Code and automation, select Pages
c. While looking at GitHub Pages settings, under Branch select the main branch for building the JupyterLite webpage and click Save.
d. After a few minutes the actions will complete and a new section will be available in the GitHub Pages settings showing the website link.
e. Clicking the Pages link should re-direct you to the lab/index.html path for the JupyterLite site. I.e. this path ccbaumler.github.io/micro becomes ccbaumler.github.io/micro/lab/index.html instead.

Changing content

Currently, materials may only be added to the content/data and content/notebooks directories of the JupyterLite repository.
If you would like an additional directory in the JL server, add a directory and file to said directory. I.e. In contents/ > Add file > documents/test.md will add the test.md markdown file to contents/documents/ directory. This will be visable in the JL server.

Edit the README.md file to reflect the goal of the JupyterLite repository. This should be a broad overview introducing the material of the session, detailing the expected learning outcomes, and explaining the contents of the data and notebooks directories for the students.
Add to the content/data and content/notebooks directories
a. Files may be written and uploaded in GitHub:
- with the Add file button that looks like a ‘+’ sign (:heavy_plus_sign:)
- from the local computer with the Add file > Upload files button on the home page of the repo
- Drag and drop files or click the choose your files link to open your file navigator tool
If files are added within subdirectory, they will automatically be placed in that directory. However, the file path may be edited as needed. Simply add or delete characters until the correct filepath is written in for the file.
For files added through the upload method, those files will need to be edited (look for the pencil icon :pencil2: after clicking on the file). Directories are automatically added to the filepath when / is included.
b. Add the file path, file name, and file contents information. Click Commit changes... when ready
c. For simple changes, Commit directly to the main branch is fine. When it comes time to rework a lot of the contents though, create a new branch and start a pull request.
d. A pull request depends on an existing branch that has been copied from another branch, usually the main branch. When opening a pull request add any information relevant to the content you are working on changing.
e. When you are happy with all the changes, Merge the pull request into main, Confirm the merge, and Delete the branch the pull request generated.
Removing to the content/data and content/notebooks directories
a. To delete entire directories, navigate to the directory and select the three dots... > Delete directory
b. To delete a file, navigate to the file and select the three dotes ... > Delete file
After selecting the three dots ..., you may need to scroll the drop-down menu to get to the Delete file selection.

Common errors

After creating the repository, I only see a static site like…

If you see something like below, either: 1. JupyterLite did not build and distribute properly, or 2. the website path is not navigating to the correct location

Does adding the /lab/index.html path load the JupyterLite session? If it does load JupyterLite or not, the following steps should fix it.

Reset the GitHub Pages site
a. Select Unpublish site
b. Save the Branch as None (make sure to click Save)
c. Save the Branch as main once again (make sure to click Save)
d. Upload some data or notebooks to the respective directories. Allow the actions to complete and navigate to the site once again.