Using VS Code or Antigravity

This guide shows how to use Visual Studio Code (VS Code) or Antigravity to contribute to the documentation site without memorizing terminal commands. Both editors provide a graphical interface for editing files, running the dev server, and working with Git and GitHub.

If you haven’t yet installed the prerequisites (Git, Node.js, a GitHub account), complete the Prerequisites section of the Getting Started guide first, then return here.

Tip

Agent note: If you are an AI agent helping a non-technical user, this guide is the recommended path. It avoids raw terminal commands in favor of UI interactions that are easier to follow. Fall back to the terminal commands in the Getting Started guide only when the UI equivalent is unavailable.

Installing Your Editor

VS Code

1. Download VS Code from https://code.visualstudio.com/.
2. Open the downloaded file and drag it to your Applications folder (macOS) or run the installer (Windows/Linux).
3. Launch VS Code.

Antigravity

1. Download Antigravity from https://antigravity.dev/.
2. Follow the installer instructions for your platform.
3. Launch Antigravity.

The rest of this guide uses VS Code terminology and screenshots, but every feature described has a direct equivalent in Antigravity. Where the two differ, a note calls out the Antigravity alternative.

Opening the Project

First Time: Clone from GitHub

1. Open your editor.
2. Open the Command Palette:
   • VS Code: Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux).
   • Antigravity: Cmd + Shift + P or use the Command Palette entry in the menu bar.
3. Type Git: Clone and select it.
4. Paste the repository URL: https://github.com/Arda-cards/documentation.git
5. Choose a folder to clone into — use your workspace folder (e.g., ~/arda-workspace). See Step 0: Workspace Folder/Directory in the Getting Started guide.
6. When prompted “Would you like to open the cloned repository?”, click Open.

Returning to an Existing Clone

• VS Code: File > Open Folder… and navigate to your documentation/ directory.
• Antigravity: File > Open Folder… or drag the documentation/ folder onto the editor icon.

The Explorer panel on the left shows the project’s file tree. Documentation content is under src/content/docs/.

Installing Dependencies

1. Open the integrated terminal: press Ctrl + ` (backtick) in VS Code, or use Terminal > New Terminal in Antigravity.
2. Type the following command and press Enter:

npm install

3. Wait for it to finish. You will see output scrolling by — this is normal. When the cursor returns to the prompt, it is done.

You only need to do this once, or again after pulling changes that modify package.json.

Starting the Dev Server

1. In the integrated terminal, run:

npm run dev

2. After a few seconds you will see a message like Local: http://localhost:4321/. Hold Cmd (macOS) or Ctrl and click the URL to open it in your browser.
3. Leave this terminal running. To run other commands, open a second terminal tab: click the + icon in the terminal panel, or use Terminal > New Terminal.

Creating a Branch

Before making changes, create a branch so your work stays separate from main.

Using the Source Control Panel

1. Click the Source Control icon in the left sidebar (it looks like a branching line).
2. At the bottom-left of the editor window, you will see the current branch name (e.g., main). Click it.
3. Select Create new branch… from the dropdown.
4. Type a branch name following the convention your-github-username/short-description — for example, janedoe/fix-typo-in-personas. Press Enter.
5. The editor switches to your new branch automatically.

Note

Branch names should start with your GitHub username followed by a slash. This is a project convention. See Step 4 in the Getting Started guide.

Editing a Page

1. In the Explorer panel, expand src > content > docs and navigate to the section and file you want to edit.
2. Click the file to open it in the editor.
3. The top of the file contains a frontmatter block between two --- lines. Do not modify or remove this block unless you know what you are changing.
4. Edit the content below the second ---. The editor provides:
   • Syntax highlighting — Markdown headings, bold, links, and code blocks are color-coded.
   • Markdown preview — In VS Code, press Cmd + Shift + V to open a side-by-side preview. In Antigravity, use the preview icon in the editor toolbar.
5. Save the file with Cmd + S. The dev server reloads automatically — check your browser to see the result.

Creating a New Page

1. In the Explorer panel, right-click the directory where the new page belongs (e.g., src/content/docs/product/).
2. Select New File.
3. Type the file name in kebab-case with a .md extension — for example, my-new-topic.md. Press Enter.
4. The file opens in the editor. Paste the following frontmatter template at the top:

---
title: "Your Page Title"
tags: [section-name, relevant-keywords]
domain: section-name
maturity: published
author: "Arda Systems"
---

5. Replace the placeholder values with your content. Write the body below the second ---.
6. Save the file and check the dev server in your browser. If the page does not appear in the sidebar, you may need to update src/sidebar.json — see Adding and Removing Sections.

For a quick formatting reference, see the Formatting Quick Reference table in the Getting Started guide, or the full Markdown Gallery.

Previewing Your Changes

With the dev server running, switch to your browser and navigate to your page. Every time you save a file, the page reloads automatically. Check that:

• Text, headings, and lists render correctly.
• Links work (click them).
• Code blocks show syntax highlighting.
• The page appears in the sidebar (for new pages).

Committing Your Changes

When you are satisfied with your edits, it is time to save them to Git.

Stage Your Files

1. Click the Source Control icon in the left sidebar.
2. Under Changes, you will see a list of modified files. Hover over each file you want to include and click the + icon to stage it.

Caution

Only stage files you intentionally changed. Do not click Stage All Changes unless you are sure every listed file should be included. See the caution in the Getting Started guide for details.

Write a Commit Message

3. In the Message text box at the top of the Source Control panel, type a short description of what you changed. Good examples:
   • Add getting-started guide for new contributors
   • Fix broken link in personas section
   • Update inventory use case with new field descriptions

Commit

4. Click the checkmark icon (or press Cmd + Enter) to commit.

Your changes are now saved locally in Git on your branch.

Pushing to GitHub

After committing, push your branch to GitHub so others can see it.

1. In the Source Control panel, click the … menu (three dots) and select Push. If this is the first push for your branch, the editor may ask to publish the branch — click OK or Publish Branch.
2. Alternatively, click the cloud/upload icon next to the branch name in the bottom status bar.

If the push is rejected because your branch is behind main, the editor will prompt you. Select Pull and Rebase, then push again.

Creating a Pull Request

Once your branch is pushed, you need to create a pull request (PR) so the team can review and merge your changes.

The PR description is prefilled by the repo’s PR template (.github/pull_request_template.md). It contains four sections: ## Summary, ## CHANGELOG, ## Closes, ## Verification. The ## CHANGELOG block is required — changelog-check will fail your PR if it’s missing or empty. Do not edit CHANGELOG.md directly in your commits; the post-merge assembly workflow owns that file. Full conventions are in Getting Started — Step 10.

Option A: GitHub Website

1. Open https://github.com/Arda-cards/documentation in your browser.
2. GitHub shows a yellow banner: “your-branch had recent pushes — Compare & pull request”. Click it.
3. The description is prefilled by the template. Fill in:
   • Title — a short summary of your change.
   • Under ## Summary — what you changed and why.
   • Under ## CHANGELOG — keep the category headings (Added / Fixed / etc.) that apply, add bullets under them, delete the ones you don’t need.
   • ## Closes — link issues this PR closes (optional).
   • ## Verification — what you checked locally and on the preview deploy.
4. Click Create pull request.

Option B: VS Code GitHub Pull Requests Extension

1. Install the GitHub Pull Requests extension from the Extensions panel (Cmd + Shift + X, search for “GitHub Pull Requests”).
2. After installing, a GitHub icon appears in the left sidebar. Click it.
3. Click Create Pull Request. The extension loads the repo’s template into the description editor.
4. Fill in the title and complete the template sections (especially ## CHANGELOG), then click Create.

Option C: Antigravity Built-in GitHub Integration

Antigravity has built-in GitHub support. Use the GitHub panel in the sidebar to create a pull request directly from the editor. The PR template is loaded automatically; fill in the title and the template sections, especially ## CHANGELOG.

Tip

Agent note: If the user has the GitHub CLI installed (gh --version), prefer gh pr create from the integrated terminal — it auto-loads the template into the body. Avoid --body "..." unless you intentionally want to override the template (in which case make sure the override still contains a valid ## CHANGELOG section).

Pulling Updates from Main

Before starting new work, make sure your local copy is up to date.

1. Switch to the main branch: click the branch name in the bottom-left corner and select main.
2. Pull the latest changes: click the … menu in Source Control and select Pull, or use the sync icon in the status bar.

If you are already on a feature branch and want to incorporate recent changes from main:

1. Open the Command Palette (Cmd + Shift + P).
2. Type Git: Rebase Branch... and select it.
3. Choose origin/main as the base.

Useful Editor Features

Markdown Preview

• VS Code: Cmd + Shift + V opens a preview tab. Cmd + K V opens a side-by-side preview.
• Antigravity: Click the preview icon in the editor toolbar, or use the Command Palette and search for “Markdown Preview”.

Search Across Files

To find a page or a piece of text across the entire project:

• Cmd + Shift + F opens the search panel.
• Type your search term. Results appear grouped by file. Click a result to jump to it.

File Navigation

• Cmd + P opens the quick-open file picker. Type part of a file name to jump to it instantly.

Side-by-Side Editing

• Drag a file tab to the right edge of the editor to open it in a split view. This is useful for comparing two pages or editing while viewing a reference.

Troubleshooting

Editor does not recognize Git — Make sure Git is installed and available in your system PATH. Restart the editor after installing Git.

Source Control panel is empty — You may have opened a single file instead of the project folder. Use File > Open Folder… and select the documentation/ directory.

Terminal commands not found — The integrated terminal inherits your system PATH. If npm or git are not found, they may not be installed or your shell profile may not be loaded. Try opening a new terminal tab, or use the external Terminal.app to run the command.

Push fails with “permission denied” — You may need to authenticate with GitHub. VS Code prompts you to sign in the first time you push. In Antigravity, check Settings > GitHub to configure your account.

Merge conflicts — If your branch conflicts with main, the editor highlights the conflicting sections in the file with colored markers. For each conflict, choose Accept Current Change, Accept Incoming Change, or Accept Both Changes. After resolving all conflicts, stage the files and commit.