Contributing to BobDocs

BobDocs uses VitePress, which turns simple text files (Markdown) into the website you see online.

---

The Rules of the Road

To keep the documentation stable and high-quality, we follow a simple workflow.

1. Protect the Main Branch: You cannot upload changes directly to the main branch. It is "protected," meaning it only accepts changes that have been reviewed.
2. Use Branches: Always create a new "feature branch" for your work (e.g., update-metrics or fix-typo).
3. Push to Remote: You'll upload your branch to GitHub and create a Pull Request (PR).
4. Pass CI Checks: Our automated system (CI) will check your work for errors. These checks must pass before your changes can be merged into the main site.

---

Step-by-Step Setup

If you don't have the code on your computer yet, follow these steps:

1. Get the Code:

   Open your terminal/command prompt and run:

   git clone https://github.com/BobDyn/BobDocs.git
   cd BobDocs

2. Install Tools:

   Make sure you have Node.js installed. Then run:

   npm install

3. See Your Changes Live:

   Run this command to start a private version of the website on your computer:

   npm run dev

   Open http://localhost:5173 in your browser. As you save files, the page will update automatically!

---

How to Contribute (The Workflow)

1. Create a Branch

Before you start typing, create a new branch:

git switch -c your-branch-name

2. Write Your Content

Most of the work happens in the docs/ folder. Files end in .md (Markdown).

• Frontmatter: Every file needs a small header at the very top:

  ---
  layout: doc
  title: Your Page Title
  ---

• Math: We support LaTeX!

  Inline: $a = F/m$

  Blocks:

  $$
  a_y = \frac{v^2}{R}
  $$

• Headings: Use # for the big title, ## for sections, and ### for sub-sections.

3. Add to the Navigation (If needed)

If you created a new file, add a single entry to docs/.vitepress/config.ts — just a page title and URL path. The ## section headings in your file are picked up automatically; you don't need to list them manually.

If you're editing an existing file, renaming or adding ## headings is all you need — the sidebar updates on the next build with no config change required.

4. Check for Errors

Run the build command to make sure there are no broken links or math errors:

npm run build

5. Submit Your Work

Once you're happy with your changes:

git add .
git commit -m "Briefly explain what you changed"
git push origin your-branch-name

Then, go to the GitHub repository and click the green "Compare & pull request" button.

---

Advanced Features

Sidebars & "On this page"

The right-hand "On this page" menu is automatic! It pulls from your ## and ### headings. The left-hand sidebar order determines the "Next" and "Previous" buttons at the bottom of the page.

Custom Components

If you need complex interactive plots (like a PID simulator), we use Vue components. You can drop them into Markdown like this:

<PIDPlot />

Check docs/.vitepress/theme/components/ to see what's available.