1. Project Setup
Do this on Day 1 — every time
6 min read
The most important rule of reproducible research: set everything up before you start collecting or analysing data, not after. Retrofitting version control and archiving at the end of a project is painful and error-prone.
This page walks through everything you need to do on Day 1 of a new research project.
Get the starter template
Here you can download a full working example project that you can modify for your own research — folder structure, analysis.qmd, index.qmd, placeholder data, all ready to go and rendering out of the box, with every file marking exactly what to replace with FILL IN comments.
⬇ Download the .zip Use the GitHub template →
Not sure what you’d actually get? See the manuscript this template renders — HTML · PDF · Word
Prefer to build it up yourself, piece by piece? Follow the steps below to create the same structure from scratch.
1.1 Create your project folder structure
A consistent folder structure makes your project navigable by anyone — including your future self six months from now.
my_paper/
├── _quarto.yml # project config, bibliography, output format
├── index.qmd # manuscript: intro, methods, results, discussion
├── analysis.qmd # all R code: cleaning, models, figures, tables
├── data/
│ ├── raw/ # original data — NEVER modify this folder
│ └── derived/ # cleaned data produced by analysis.qmd
├── outputs/
│ ├── figures/ # figures generated by analysis.qmd
│ └── tables/ # tables generated by analysis.qmd
├── references/
│ └── references.bib # bibliography
└── README.md # write this on Day 1Never overwrite, edit, or delete anything in data/raw/. Your analysis scripts should only ever read from this folder and write to data/derived/. This means you can always re-run your entire analysis from scratch.
Your _quarto.yml
A minimal starting configuration:
project:
type: default
format:
pdf:
documentclass: article
papersize: a4
fontsize: 12pt
linestretch: 2
toc: false
html:
toc: true
bibliography: references/references.bib
csl: your-journal.cslQuarto renders PDF output through LaTeX, the typesetting system academic publishing has used for decades — proper margins, line spacing, font metrics, and pagination come for free from documentclass: article. You’re not fighting Word’s page-layout quirks to match a journal’s format; you get correct academic typesetting the moment you hit render.
csl is worth setting up
The csl (Citation Style Language) file controls exactly how in-text citations and the reference list are formatted — and journals are picky about this. Instead of manually reformatting every reference by hand, download your target journal’s .csl file from zotero.org/styles (most journals are already there), point csl: at it, and every citation in your manuscript instantly matches that journal’s house style. Switching journals later is a one-line change, not a re-format.
1.2 Initialise Git in Positron
Positron has Git built in via the Source Control panel — no terminal needed.
Step 1
Open your project folder in Positron: File → Open Folder
Step 2
Click the Source Control icon in the left sidebar (it looks like a branch/fork symbol)
Step 3
Click “Initialize Repository” — Git is now tracking your project
Step 4
Stage all your initial files by clicking + next to each file (or “Stage All Changes”), write a commit message like "initial project setup", and click the tick to commit
What Git actually does
Git keeps a complete history of every change you make to every file. Think of it as an unlimited undo button with descriptions. Every time you commit, you create a save point you can always return to.
Create a .gitignore file in your project root to tell Git which files to ignore:
# R
.Rhistory
.RData
.Rproj.user/
_freeze/
# Large data files (upload these directly to Zenodo instead)
data/raw/*.csv
*.xlsx
# Output files (regenerated by analysis.qmd)
outputs/
# renv cache
renv/library/1.3 Push to GitHub
Step 1
In the Source Control panel, click “Publish to GitHub”
Step 2
Choose Public repository — this is what allows reviewers and readers to access your code
Step 3
Give it a clear, consistent name, e.g. koura-habitat-mesocosm — lowercase with hyphens or underscores is a common convention, but not a requirement
Step 4
Click Publish — Positron pushes everything automatically
Your code is now publicly available at https://github.com/yourusername/koura-habitat-mesocosm
1.4 Set up renv
renv records the exact version of every R package you use, so anyone can recreate your environment exactly.
In the Positron terminal:
install.packages("renv")
renv::init()
renv::snapshot()This creates a renv.lock file. Commit this file to GitHub — it is one of the most important files in your repository.
When someone else downloads your repository and runs renv::restore(), they get exactly the same package versions you used.
Without renv, a figure that looks one way in your R version 4.3 might look completely different when a reviewer runs it in R 4.1. Package updates change defaults, colour schemes, and even statistical outputs. renv eliminates this problem.
renv is R-specific, but the same idea applies: use venv + requirements.txt, conda + environment.yml, or Poetry to lock your dependencies, and commit that lockfile the same way you would renv.lock. Everything else on this page — folder structure, Git, GitHub, Zenodo — works exactly the same regardless of language.
1.5 Connect GitHub to Zenodo (one-time setup)
This is the step that makes the GitHub → Zenodo workflow automatic. Do it once and it works for every repository.
Step 1
Go to zenodo.org and log in with your GitHub account
Step 2
Go to your account Settings → GitHub
Step 3
Find your repository koura-habitat-mesocosm and toggle it ON
Zenodo now watches this repository. When you create a “release” on GitHub later (at acceptance), Zenodo automatically archives a permanent snapshot and assigns a DOI.
1.6 Write your README
The README is the first thing anyone sees when they visit your GitHub repository. Write it on Day 1 and update it as you go.
# Kōura habitat mesocosm study
Analysis and manuscript for: Raven, O.V. et al. (in review).
[Paper title]. [Journal name].
## How to reproduce the analysis
1. Clone this repository
2. Open the project in Positron
3. Run `renv::restore()` to install all required packages
4. Render `analysis.qmd` to generate all figures and tables
5. Render `index.qmd` to generate the full manuscript
## File structure
- `analysis.qmd` — all data cleaning, modelling, and figures
- `index.qmd` — manuscript text
- `data/raw/` — original unmodified data
- `data/derived/` — cleaned data produced by analysis.qmd
- `outputs/figures/` — all generated figures
## Software
- R version 4.4.x
- Quarto version 1.5.x
- See `renv.lock` for full package list
## License
Code: MIT | Data and content: CC BY 4.0