Setting Up Your Course Workspace in VS Code

What is the course workspace?

The course workspace is where you keep everything you write and build this term. It is a VS Code folder, copied from a GitHub template, that holds your journals, literature notes, project files, and reusable templates, all version-controlled with Git. Everything is plain Markdown and plain files, so you own your work and can read it anywhere.

There is no separate notes app and no plugins to configure. You organize your work with folders and write in Markdown, the same tools you use for the rest of the course.

Step 1: Install VS Code, R, and Git

If you have not already, follow the Install VS Code guide. You also need R and Git, covered in Install R and Getting Started with GitHub.

Step 2: Create your copy from the template

  1. Go to the v2v-workspace repository.
  2. Click Use this template, then Create a new repository.
  3. Name it mc451-workspace or mc501-workspace, and leave it Public. Your graded submission is the repository URL, so it has to be one anyone can open.
  4. Click Create repository.

You now have your own copy of the workspace on GitHub.

Step 3: Clone it into VS Code

  1. Copy your new repository’s URL (the green Code button).
  2. In VS Code, open the Command Palette: Ctrl+Shift+P (Windows) or Cmd+Shift+P (Mac).
  3. Type Git: Clone and press Enter.
  4. Paste your repository URL.
  5. Choose a folder you will remember, for example Documents/MC451/.
  6. When VS Code asks, click Open to open the cloned workspace.

Step 5: Read the README

Open README.md in the file explorer (left sidebar). It explains the folder structure and how to start a journal entry.

The workspace is pre-organized:

  • 00_Inbox captures ideas quickly.
  • 01_Journal holds your weekly reflections (committed to GitHub).
  • 02_Literature holds reading notes and Zotero annotations.
  • 03_Project holds your active research work.
  • 04_Resources holds images, PDFs, and attachments.
  • **_templates** holds reusable templates.

Those capitals are part of the folder names. Git treats 01_Journal and 01_journal as two different folders, so match what you see in the file explorer.

Follow this structure to stay organized.

Step 6: Start a journal entry from the template

  1. In the file explorer, open _templates/journal-entry.md.
  2. Right-click it and choose Copy, then right-click the 01_Journal/ folder and choose Paste.
  3. Rename the copy for the week, for example week-02-curiosity-and-trust.md.
  4. Fill in the prompts and write your reflection.
TipKeep files findable

Name files in lower case with hyphens instead of spaces (week-02-curiosity.md, not Week 2 Notes.md). Consistent names sort cleanly and never break links.

Step 7: Basic Markdown syntax

Notes use Markdown. The essentials:

Syntax Result
# Heading 1 Large heading
## Heading 2 Medium heading
**Bold text** Bold text
*Italic text* Italic text
- List item Bullet list
1. Numbered item Numbered list
[Link text](https://example.com) Hyperlink
> Quote Block quote
`code` Inline code

VS Code shows a live preview with Ctrl/Cmd+Shift+V.

Step 8: Commit and push your work back to your repository

Your workspace is a copy of the course template that belongs to you. Sending your work back up to it is how you get a backup, a history you can walk through, and the version control habit the White Paper depends on.

Committing is not submitting. Graded work is turned in through Blackboard. Commit as well, always, but an assignment that was committed and never submitted has not been turned in.

Before your first commit: tell Git who you are

Do this once per computer, before anything below. Git stamps every commit with a name and an email address, and it refuses to commit until it has them. In a VS Code terminal (Terminal, New Terminal):

git config --global user.name "Your Name"
git config --global user.email "you@siue.edu"

Use an address attached to your GitHub account, either the one you signed up with or one you added under Settings, Emails. A commit made with any other address still saves, but GitHub cannot match it to your profile, so your work shows up under a stranger’s name, and your repository is how your work is read and graded.

Check that it took:

git config --global --list

You should see your user.name and user.email in the output. Signing in to GitHub in VS Code does not set these. They are two separate things, and doing one is not doing the other. There is more on this in Getting Started with GitHub.

The weekly rhythm

Save your files first. Then, in VS Code’s Source Control panel (the branch icon in the left bar): stage your changes with the +, write a short message, click Commit, then Sync Changes. Or in the terminal:

git add .
git commit -m "Week 2 journal and literature notes"
git push

Write messages a stranger could read: what changed and why, never “stuff”.

Prove it actually landed

A push that fails often fails quietly. After pushing:

git log --oneline
git status

You should see your commit at the top of the log, and git status should say your branch is up to date with origin/main. Then open your repository on github.com and refresh. If your commit is not visible in the browser, it did not push, whatever the terminal appeared to say.

The first push asks you to sign in

It will, and your GitHub password will not work. That is not a mistake on your part: GitHub stopped accepting passwords for this in 2021 and wants a token instead.

VS Code handles the whole exchange for you. When the browser window opens, sign in and authorise it. It asks once and then never again on that machine.

If you would rather do it by hand, or the browser flow loops, generate a personal access token at github.com, Settings, Developer settings, Personal access tokens, Tokens (classic), give it the repo scope, and paste the token when git asks for a password. Save it somewhere safe. GitHub shows it once.

Troubleshooting

The extension prompt never appeared

Open the Extensions view (Ctrl/Cmd+Shift+X), type @recommended, and install the listed extensions.

I cannot push to GitHub

Confirm you are signed in to GitHub in VS Code (the Accounts icon, bottom-left) and that you cloned your copy of the repository, not the original template.

Git says “Author identity unknown”

The rest of the message is Please tell me who you are. It is not about your GitHub password or your login, and you get it the same way whether you commit from the terminal or from the Source Control panel, because both run the same Git underneath. It means the two commands in Before your first commit above have not been run yet on this computer. Run them, then commit again. Nothing you wrote is lost.

VS Code opened the wrong folder

Use File > Open Folder and select the workspace folder you cloned, not a parent folder above it.

Next steps

  1. Install VS Code, R, and Git.
  2. Create your copy from the template and clone it.
  3. Install the recommended extensions.
  4. Read README.md.
  5. Start your first journal entry from the template.
  6. Begin Phase I: The Journalist.

Resources

Stuck? Come to office hours.