# Creating a JupyterLite Server for the classroom

[TOC]

## Set up

1. Navigate to [Titus' template](https://github.com/ctb/2025-jupyterlite-template)
- https://github.com/ctb/2025-jupyterlite-template

2. In the upper right, click `Use this template` > `Create a new repository`


:::info
Note: The repository name will be the path of the url. I.e. If I name a repo `stats101` and my user name is `spartacus`, the url will be `spartacus.github.io/stats101`.

You may create any number of templates and store any number of repositories.

Repositories may also be public or private. Private may require an upgraded subscription. Look into signing up for [github for teachers](https://github.com/education) to bypass a subscription fee.
:::

3. Add a `Repository name` and click `Create repository` to generate a ***public*** repository hosting a JupyterLite session for your courses/curriculum.


4. 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.



:::info
This `GitHub Action` may fail, showing a red 'X' (:x:) instead of the green check (:heavy_check_mark:) for a successful run.
:::

5. 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

:::info
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.
:::

1. 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.


2. 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


:::info
Note: 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.

3. 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`


:::info
Note: 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.

1. 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.

:::warning
If this workflow does not fix the issue, reach out to me at [e-mail]
:::

## Missing features