Contribute - Surf Deeper

Contributing Made Easy

Follow these simple steps to start contributing, even if you're new to coding!

1. Download VS Code

Visual Studio Code is a free code editor for Windows, Mac, and Linux.

2. Sign Up for GitHub

Create a free account to contribute and track your changes.

3. Set Up Copilot

In VS Code, go to Extensions and install GitHub Copilot. Sign in with your GitHub account.

4. Fork & Clone the Repo

Go to the repo and click Fork.
Then, copy your repo link and run:
git clone https://github.com/YOUR-USERNAME/surfdeeper.git

5. Add/Edit Guides & Spots

Edit or add Markdown files in src/content/concepts/, src/content/skills/ or src/content/spots/. Copilot will help you write!

Guides are now split into typed collections: concepts and skills. Use stable IDs with magic links. Each page is a single concept or skill. Link by ID instead of paths.

In the terminal, run:
git add .
git commit -m "Add new guide/spot"
git push

Concepts: src/content/concepts/

Skills: src/content/skills/

7. Make a Pull Request

Go to your fork on GitHub, click Compare & pull request, add a description, and submit!

Visit the Project Repo

Update Spot Coordinates

If you notice a spot's pin is in the wrong location on the map:

Go to the Spots page
Click on the spot marker to open the popup
Click "📍 Pin in wrong location?"
Drag the pin to the correct location
Click "Done - Show Instructions" to get the new coordinates
Follow the GitHub link to submit your correction

The coordinates are stored in the frontmatter of each spot's markdown file at src/content/spots/.

How it works

Guides live in a flat folder and use concept IDs with magic links. Each guide is one concept. Link concepts by ID instead of paths.

Guides: place files in src/content/guides/ (flat)
Frontmatter: id (required), title (required), description (optional), level, paths[], dependsOn[], leadsTo[], appliesTo[]
Magic links in Markdown: [Label](:concept-id)
Relationships by ID: dependsOn: [some-id], leadsTo: [next-id]

See the canonical docs for details and examples: Contributing · Knowledge Architecture.

Quick steps

Open the concepts folder or skills folder.
Copy an existing page into src/content/concepts/ or src/content/skills/.
Set a unique id in frontmatter and edit the title and content.
Use magic links like [Pop-up](:pop-up) in content.
Open a PR. We’ll review quickly.

PR workflow (short)

Use the GitHub UI for quick edits, or develop locally with npm run dev. Keep changes small and follow existing patterns. Link sources when helpful.