Team Documentation

This guide is designed to introduce non-technical members of our team to contribute to new documentation to this website.

If you didn’t read the entries regarding Git/GitHub I advise you read them here

In order to contribute documentation, there are several tools and skills you will need to have a solid understanding of.

Install tools

1. Visual Studio Code + Dev Containers

   1. Download VS Code for your platform from code.visualstudio.com.
   2. Run the installer and launch VS Code once it completes.
   3. Install the Dev Containers and GitHub Pull Requests extensions from the Extensions view.
   4. Sign in with your Microsoft or GitHub account to sync settings between machines (optional but recommended).

   5. Verify the command line launcher works: open a terminal and run:

      code —version

2. Node.js (includes npm)

   1. Grab the current LTS installer from nodejs.org (macOS pkg, Windows .msi, or Linux instructions).
   2. Run the installer and accept defaults so Node, npm, and PATH entries are configured automatically.
   3. Reopen your terminal to ensure the new PATH is picked up.

   4. Confirm both Node and npm are available:

      node —version
      npm —version

   Note

   Installing the LTS channel ensures compatibility with Astro, Bun, and our CI builds.

3. WSL 2 + Docker Desktop (Windows)

   1. Open PowerShell as Administrator and install WSL + Ubuntu:

      wsl —install —distribution Ubuntu

   2. Restart when prompted, then create your Linux username/password.

   3. Update packages in Ubuntu:

      sudo apt update && sudo apt upgrade -y

   4. Download Docker Desktop, run the installer, and enable the WSL 2 backend.
   5. After Docker launches, go to Settings → Resources → WSL Integration and turn it on for Ubuntu.

   6. Verify everything is wired up from PowerShell or the VS Code terminal:

      wsl —list —verbose
      docker version

   Caution

   Docker Desktop needs to be running before you attach a Dev Container; keep it open in the system tray.

4. Google Chrome

   1. Download Chrome from google.com/chrome.
   2. Run the installer (drag the app into Applications on macOS, or follow the Windows wizard).
   3. Sign in with your robotics Google account to sync bookmarks and extensions.
   4. Install the React DevTools and Lighthouse extensions to help debug documentation changes.
   5. Set Chrome as your default browser so Dev Server links open there automatically.

5. Bun Runtime

   1. Open a terminal and run the official install script:

      curl -fsSL https://bun.sh/install | bash

   2. Restart your terminal (or source your shell profile) so the bun binary is on PATH.
   3. Inside the repo root, run bun install once to install dependencies with Bun’s package manager.

   4. Verify Bun is available:

      bun —version

   Caution

   The installer modifies your shell profile (.bashrc, .zshrc, etc.). Review the changes if you keep custom PATH tweaks.

---

Clone the Repository & Open the Dev Container

1. Pick a working folder (for example ~/Projects) and clone the docs site:

   git clone https://github.com/BC-Robotics-4504/bcr-docs.git
   cd bcr-docs

2. Launch VS Code from the repo root so the Dev Container definition is detected:

   code .

3. When VS Code prompts to “Reopen in Container,” click it. Confirm Docker Desktop is running first or the build will fail.

4. Wait for the container to build (first run takes 3‑5 minutes). Once it finishes you’ll see Dev Container: bcr-docs in the status bar.

5. Open a terminal inside VS Code (`Ctrl+“) and install dependencies if needed:

   bun install

6. Start the local dev server:

   bun run dev

   VS Code will forward the port; open the browser link to preview live changes.

Tip

If you ever need to rebuild the container, use the Command Palette → “Dev Containers: Rebuild Container.”

---

Where to Put Documentation

• All docs live under src/content/docs. Group topics by the existing folder structure (programming, electronics, etc.).

• Create a new .mdx file in the correct folder. Example: src/content/docs/programming/Contributing/new-guide.mdx.

• Each file begins with frontmatter:

  ---
  title: Awesome Topic
  description: 'One-line summary'
  sidebar:
    order: 5
  ---

• After the frontmatter, write Markdown as usual. MDX adds the ability to import components (e.g., Aside, Steps) and use them inline.

• Basic MDX reminders:

  • Headings use #, ##, ###.

  • Wrap code blocks with triple backticks and add a language (```bash).

  • Use JSX-style syntax for components:

    import { Aside } from '@astrojs/starlight/components';
    
    <Aside type="note">Short callouts keep readers on track.</Aside>

• Keep sentences short and add bullet lists for instructions; Starlight prefers concise paragraphs.

Note

Run bun run lint:content (if available) before committing to catch broken frontmatter or invalid MDX.

---

Git Workflow: Branch, Commit, and PR

Follow this flow so your changes are easy to review.

1. Make sure main is up to date:

    git checkout main
    git pull origin main

2. Create a feature branch that describes your work:

   git checkout -b docs/add-contributing-guide

3. Edit or add MDX files, then check what changed:

   git status

4. Stage and commit with a descriptive message:

   git add src/content/docs/programming/Contributing/docs-site.mdx
   git commit -m "docs: expand contributor install & workflow guide"

5. Push the branch to GitHub:

   git push -u origin docs/add-contributing-guide

6. Open GitHub, you’ll see a “Compare & pull request” banner. Click it, fill in the summary, and submit the PR.

7. Share the PR link in the team channel for review. Once approved, merge via the GitHub UI.

Caution

Never commit directly to main. Always work through a feature branch and pull request so every change is reviewed.