Lab 0: Getting Started

The goals for this tutorial are:

The assignment requirements are as follows:

  1. Replicate the local environment created in class on your own computer (Installations)
  2. Fork this repository, set up github pages, and initialize your upstream repository (Github Setup)
  3. Edit the index.md file to include:
    1. Markdown: A page header (#), some smaller header (## or ###), and some text content
    2. HTML: A table, a list, and an image
    3. JS: include at least one Input element that changes a visible reference on the dashboard
  4. Submit your deployed link as a comment on the lab 0 commons post.

Installations

The first step is to install all the appropriate software to get our environment together. Please install the following on the computer you intend to complete all the labs from.

Note: while VS code is an application, the other softwares are installed via your terminal or bash. If this is your first time working with your terminal, check out working with your terminal.

Github Setup

You can read more about forking, syncing, and the overall github flow here.

1. On Gitub, within to our main repository and fork this repository into your own account.

To do this, click on the "fork" button on the top right of this github account.

This creates a clone of our class repository in your own github account. After the fork, you can see this worked by confirming your github username appears before the repository name:

This repository is your personal copy of the existing repository. This will be where you do all your lab work, and will include the deployed links that you will submit when turning in your assignments.

2. On GitHub, navigate to your fork of the repository, clone it to your local computer, and install dependencies.

To do this, navigate to the folder where you want to save your files (I like to save mine in Documents/Repositories). (Hint: cd or 'change directory' will help you get there through terminal). Then use the git clone command and paste the git url from the big green "code" button:

Copy the link inside there and use it after the git clone command in the terminal details below:

# from Terminal:

# navigate to where you want to save your code
$ cd PATH_TO_YOUR/FOLDER

# clone your fork to your local computer
$ git clone https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025

# `cd` (change directory) into this repository
$ cd Interactive-Data-Vis-Fall2025

We do this so that you can keep your local branch synced up with the main course repository when we update the material. With this set up, you can simply pull in the new changes from our original class repository.

#See current remote branches:

$ git remote -v
> origin	https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025.git (fetch)
> origin	https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025.git (push)

# currently this is only tracking your version of the repository

Add an upstream remote branch so you can keep yours synced with the main class repository:

$ git remote add upstream https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git

Check remote branches again to ensure that the update worked. You should see 2 sets of branches, origin which links back to your fork, and upstream which references back to the course repository:

$ git remote -v
> origin	https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025.git (fetch)
> origin	https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025.git (push)
> upstream	https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git (fetch)
> upstream	https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git (push)

# now we are tracking both the original and your version of the repository

4. Set up your Github Pages for your deployment

We use Github Pages to serve our websites publicly. Github Pages is static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

To set up your github pages site, you can go to your repository's Settings tab and then scroll down to Pages section. Select Github Actions as source ("Deploy from a branch").

The workflow code is already included in the main class repository, but disabled by default. The workflow file is something called a .yml file, located in the .github file at .github/workflows/deploy.yml. This workflow includes instructions telling github to build and deploy your app whenever you push to main. You shouldn't have to change this file at all, but here's the key commands of the file for your understanding:

on:
  # Run this workflow whenever a new commit is pushed to main.
  push: {branches: [main]}

jobs:
  # define the job
  deploy:
    ...
    steps:
      - run: npm run build # builds the app
      ...
      - name: Deploy # run the github deploy pages action
        id: deployment
        uses: actions/deploy-pages@v4

To deploy your app on push, you need to enable these workflows. Navigate to the "actions" tab, and click "I understand my workflows, go ahead and enable them". The app will now deploy on push.

When you push your changes up to github, then your site will automatically be redeployed and be avallable at https://[YOUR_USERNAME].github.io/[YOUR_REPOSITORY_NAME]/.

Once you have pushed a change, you can see all the deployments triggered from pushed in the deployments section of your repository page. These will not be triggered until you make a change to your repo and push it back up to github.

NOTE: You must navidate in the URL to a folder with an index.html, or else you will get a 404. This will take a few minutes to update with any pushed changes.

5. Install dependencies and begin local development

The cloned repository already has packages and dependencies set up to get started with Observable Framework. The package.json file includes the details of the packages required to begin development.

To install and get started, run the following in your terminal:

# within the repository directory, install the packages
$ npm install

# attempt to enter development
$ npm run dev

> dev
> observable preview
> Observable Framework v1.13.3
> ↳ http://127.0.0.1:3001/

Your terminal will now begin serving the code at the listed url. This can be http://127.0.0.1:3000/ or another port (e.g., :3001). The listed url in your terminal is where your code is served. Navigate to that link in your browser. You should see the code from the class repository.

To exit out of this live updating serve, in the terminal window in which the serve is taking place, type CNTRL or CMMD + c

6. Push up and deploy your changes

When you have made a change that you want to keep, you can commit your changes. VS Code has some great tools built in to help with this process, which are a bit easier, or you can leverage the command line.

To use VS Code tools:

  1. Open the "version control" panel on the left side of your application. You should see a list of changes and a place to add a comment.
  2. Click on the "+" next to each change to add it to the staged changes.
  3. Add a comment about your work, then click "commit". Just because you have committed the changes does not mean they are pushed to your repository yet.
  4. Click the three dots and click "push" to send your commit to github.

To use the command line:

# see which files have changes associated with them
$ git status

# add, or 'stage', files or folders for this commit
$ git add [path/fileName]
# you can also do the shorthand git add . to add all files

# commit the files with a brief explanation of what you are changing
# ex: `git commit -m 'add bar chart legend`
$ git commit -m 'message regaring what changes you are commiting'

When you are ready to push up your code to your remote repository, you can run:

$ git push

That's it! Now you are ready to create, update, and deploy your own dashboards 🎉!

Appendix

Working with your terminal

Your computer, mac or pc, includes a command line interface that lets you communicate with your operating system. For macs, that app is called "terminal", and on windows machines, its the "command prompt".

Mac Terminal Command Prompt

More resources to understand these interfaces:

Keeping your repository synced

As the semester progresses, updates may be pushed to the class repository. The following terminal commands can keep your repo synced. Make sure to do this before working on new code to ensure that you are working off of the latest updates.

# pulls the upstream changes and stores them in `upstream/main`
$ git fetch upstream

# merges the changes from upstream into your current branch
$ git merge upstream/main

(You can read more information about this process here)

Helpful terminal commands for navigation

Windows Command Prompt (CMD)

macOS/Linux Terminal