Appendix B — How to add chapters

This appendix is the working guide for the authors (especially Érico) to keep adding chapters as the research progresses — leaving the full history in Git.

B.1 What you need to have installed

Git (and an account with access to the repository);
Quarto (recent versions of RStudio already ship with Quarto);
R with the terra package (for the chapters with maps): install.packages("terra").

B.2 Editing in RStudio (recommended)

The repository includes the tutorial-trigrs.Rproj file — double-click it (or use File → Open Project in RStudio) and the whole project opens in RStudio:

The .qmd chapters appear in the Files pane — open, edit (RStudio’s Visual editor lets you edit them as if they were a Word document), and save;
Click Render (or Build → Render Book) to see the result in the browser;
Use RStudio’s Git tab to Commit (check the files → message → Commit) and Push — no command line needed;
Within 1–2 minutes the public site is updated.

B.3 Workflow (command line)

# 1. Clone (first time only)
git clone https://github.com/sedec-dpm-cgnat/tutorial-trigrs.git
cd tutorial-trigrs

# 2. Always update before you start working
git pull

# 3. Create/edit a chapter: e.g., 06-bacia-hsl.qmd
#    (use an existing chapter as a template)

# 4. Register the new chapter in _quarto.yml (the "chapters:" list)

# 5. Render and check locally (opens the site in the browser)
quarto preview

# 6. Render the final version (generates the site in the docs/ folder)
quarto render

# 7. Commit and publish
git add -A
git commit -m "Add chapter: grid preparation for the HSL watershed"
git push

When you run git push, GitHub Pages automatically publishes the contents of the docs/ folder — within 1–2 minutes the site is updated.

The English edition

The English sources live in the en/ folder, with their own en/_quarto.yml (new chapters must be registered there as well, with the same file names). A full render of the Portuguese book cleans the whole docs/ folder, including the English site in docs/en/; that is why the post-render hook _render-en.R (declared in the root _quarto.yml) re-renders the English edition right after it. To render only the English edition, run cd en followed by quarto render. Always check that docs/en/ is present before committing. Case-study figures live in figuras/<caso>/ at the repository root (copied as a whole to docs/figuras/); in the English chapters, use ../figuras/<caso>/....

B.4 Good practices

One chapter per completed step (e.g., DEM preparation, calibration, sensitivity analysis). Short, frequent chapters are worth more than one giant chapter at the end.
Small commits with descriptive messages — they are the research’s “lab notebook”.
Mistakes and dead ends also deserve to be recorded (a “what did not work” section is gold for whoever comes next — and for the dissertation).
Heavy data (DEMs, large shapefiles) do not go into Git — they stay in the project’s network folder/OneDrive; the chapter documents their origin and preprocessing.
Figures generated by code (R/QGIS) are preferable to screenshots — they are reproducible.

B.5 Structure of a typical chapter

# Chapter title

Context: what this step does and why.

## Data used
Source, resolution, CRS...

## Procedure
Step by step (commands, chosen parameters, and their justification).

```{r}
# R code that generates figures/tables from the results
```

## Results and interpretation

## Problems encountered and solutions