# Editing Safely

## Editing Safely

**Skill level:** Complete beginner

Nothing you change in Margo is permanent if you keep checkpoints. These habits make every edit safe to try, whether you edit by hand or with AI.

### The Safe Editing Loop
<Steps>

1. **Run the site** with `npm run dev`, so you see each change as soon as you save.
2. **Change one thing**, save, and look at the page. Watch the terminal too: a yellow `[forms]` line or a red `[toml-watcher]` line points at a value to fix.
3. **Make the window narrow** to see the phone layout, and open the mobile menu.
4. **Switch to dark mode** with the light/dark button in the header, and look again.
5. **Check your other languages:** open the same page under `/fr/` and `/ar/`. Each language reads its own folder, so change each one. Arabic pages read right to left.
6. **Save a checkpoint** when it works (see below).
7. **Repeat.**

</Steps>

Small steps make problems easy to find: if the page breaks, it was the last change.

### Save Checkpoints With Git
In VS Code's **Source Control** panel (or the terminal):

```bash
git add .
git commit -m "Change the hero text and add a project"
```

- **See what changed** since the last checkpoint: click a file in the Source Control panel. Removed lines are red, added lines are green.
- **Undo changes to one file**: right-click it in Source Control and choose **Discard Changes**.
- **Undo everything since the last checkpoint**: `git restore .` in the terminal.

No git? Copy the whole Margo project folder (without `node_modules/`) before a big change, and name the copy with the date.

### Before You Change Code
Content files are hard to break. Components and styles are easier to break and harder to fix. Before you edit anything in `src/layouts/`, `src/lib/`, or `src/styles/`:

- check whether the change can be made in a content file or `config.toml` instead (it usually can: many sections have several layouts, and every page can override a section with a named block)
- save a checkpoint
- run `npm run astro-check` afterwards

### Keep Ids In Step
Some files point to others by id, the file name without `.md`. The homepage hero lists project ids in `cards`, a service lists project ids in `related`, and a project can name the next one in `next`. When you rename or delete a project or service file:

- search the project for its old id and update or remove every match
- rename the file the same way in every language folder

### Run The Checks
```bash
npm run astro-check   # finds mistakes in code and in content files that have a schema
npm run build         # builds the full site, as your host will
```

Run both before every deploy. Stop `npm run dev` first, and run them one after the other, not at the same time.

`astro-check` doesn't check the files in `src/content/sections/`, `contact/`, `faq/`, and `pricing/`, so the safe editing loop above (look at the page after each change) is your check for those. Read the yellow lines in the `npm run build` output: `[site]` means `baseUrl` is still the placeholder, and `[forms]` means a form still posts to a placeholder address.

<Aside type="caution">
  Never edit files in `.astro/`, `dist/`, or `node_modules/`. They are
  generated and your changes would be lost. That includes
  `.astro/config.generated.json`: edit `src/config/config.toml` instead.
</Aside>