Onboarding Wiki

GnR stands for Get and Run. These pages are quick, step-by-step recipes for getting one of our projects onto your computer and running it. No deep explanations, just the steps.

This one is for the onboarding wiki, the site you’re reading right now.

Every command on this page is meant to be typed into Command Prompt on Windows.

Before You Start

You’ll need these installed first. If you’re missing any, follow the setup guide and come back:

You’ll also need a Codeberg account with access to the Akron-DSA organization. If you can’t see the repository when you’re signed in, ask someone on the team to add you.

1. Get the Code

Open the command line by pressing your Windows key and searching for cmd, then run the application called Command Prompt.

First, move to the folder where you want to keep your projects. For example, to use your Documents folder:

cd %USERPROFILE%\Documents

Now clone the repository:

git clone https://codeberg.org/Akron-DSA/Start-up-wiki.git

If Git asks you to sign in, a window will pop up asking for your Codeberg username and password. Sign in, and the download will continue. Git will remember you after this, so you won’t be asked every time.

When it’s done, you’ll have a new folder called Start-up-wiki with all the code inside it.

The project itself lives in a folder inside that folder, which is also called Start-up-wiki. Move into it:

cd Start-up-wiki\Start-up-wiki

Check that you’re in the right place by listing the files in the folder:

dir

You should see a file called package.json in the list.

2. Make Your Own Branch

Right now you’re on the main branch, which is the official copy of the wiki. Instead of working on it directly, make your own branch to work in. Think of it as your own folder: you can change whatever you want in it without touching anyone else’s work. (If branches are new to you, see Git Commands.)

Name your branch after your last name, followed by _workspace:

git checkout -b <LastName>_workspace

Example:

git checkout -b Smith_workspace

Branch names can’t have spaces. If your last name has a space in it, use a dash instead, like De-La-Cruz_workspace.

Check that it worked:

git branch

Your new branch should be in the list with a * next to it, which means it’s the one you’re working in.

Right now, your branch only exists on your computer. Put it on Codeberg so it’s backed up and the team can see it:

git push --set-upstream origin <LastName>_workspace

Example:

git push --set-upstream origin Smith_workspace

3. Install the Dependencies

The wiki is built on other people’s code (mainly Astro and Starlight). NPM downloads all of it for you in one command:

npm install

This can take a minute or two. When it’s done, you’ll see a message like added 300 packages, and a new node_modules folder will appear. That’s where all the downloaded code lives.

You only need to do this the first time, and again whenever someone adds a new dependency to the project. If the site ever breaks after a git pull, running npm install again is a good first thing to try.

4. Run It

Start the wiki:

npm run dev

After a few seconds it will print a few lines, including one like this:

┃ Local    http://localhost:4321/

Open http://localhost:4321/ in your web browser. You should see this wiki, running on your own computer.

localhost means “this computer.” Nobody else can see this copy of the site. It’s your own private version to experiment with.

Leave this Command Prompt window open. Closing it stops the wiki.

5. Make a Change

Let’s prove it’s really running from your copy of the code. Since the first Command Prompt window is busy running the wiki, open a second Command Prompt window and move back into the project:

cd %USERPROFILE%\Documents\Start-up-wiki\Start-up-wiki

Then open it in VS Code:

code .

In VS Code’s Explorer panel, open src > content > docs > guides > References > GnR > Onboarding Wiki.md (this page!). Change a word and save it with Ctrl + S. Switch back to your browser. The page should update on its own, without refreshing.

Since you’re on your own branch, this change only affects your workspace. The official main copy is untouched.

When you’re done, throw your change away by running this in the second Command Prompt window:

git checkout -- .

6. Stop It

To stop the wiki, click into the Command Prompt window it’s running in and press Ctrl + C. When it asks Terminate batch job (Y/N)?, type Y and press Enter.

Next time you want to run it, you only need to move into the project, make sure you’re on your branch, and start it again. No need to clone, branch, or install again:

cd %USERPROFILE%\Documents\Start-up-wiki\Start-up-wiki
git checkout <LastName>_workspace
npm run dev

Troubleshooting

`Authentication failed` or `repository not found` when cloning

Codeberg doesn’t recognize you, or you don’t have access yet. Check that you typed your Codeberg username and password correctly, and that someone has added you to the Akron-DSA organization. As mentioned in the Git setup guide, the first attempt sometimes fails, so try once more before digging deeper.

If you saved the wrong password and Git keeps using it, open the Start menu, search for Credential Manager, click Windows Credentials, find the entry for git:https://codeberg.org, and click Remove. The next time you clone, Git will ask you to sign in again.

`fatal: a branch named '<LastName>_workspace' already exists`

Either you already made your branch (run git checkout <LastName>_workspace to switch to it), or someone with the same last name got there first. In that case, add your first initial to the front, like J-Smith_workspace.

`npm error enoent Could not read package.json`

You’re in the wrong folder. Remember the project is in the inner Start-up-wiki folder:

cd Start-up-wiki

Then try again.

`'git'`, `'npm'`, or `'code'` is not recognized as an internal or external command

Command Prompt can’t find that program. Close every Command Prompt window and open a new one. If that doesn’t fix it, go back to the matching setup guide and check the Add to PATH step.

The site runs on a different port, like `4322`

Something else (probably another copy of the wiki) is already using port 4321. Either use the new address it prints, or find the other Command Prompt window and stop it with Ctrl + C.

`npm run dev` fails with errors about missing packages

Run npm install again. Someone may have added a new dependency since you last installed.