1 Contributing using RStudio

(tested on RStudio 2024.04.2 Build 764 for OSX)

Note: You need to have git installed and you need to generate a personal authentication token in your github account to be able to push your changes to the remote repo.

This has an advantage that you can edit .qmd files in visual mode and paste screenshots without having to explicitly save and link images.

Go to File -> New Project
Select “Version control”

Paste the git repo http path:

https://github.com/visualneuroscience/visualneuroscience.github.io.git

Edit the local version as you wish
To preview your changes locally, go to “Build” tab and press “Render Website”. This opens the site in your browser.
If you are happy switch to the “Git” tab, select either all or some files, stage and commit. After this, press “Push” to send the new content to github repo
Every time you start editing the R project, first press “Pull” to make sure your local version contains all the most recent changes, which may have been made by others.

1.1 Note on Windows

The difficulty on windows PC in the office has been the extreme slowness of the Git Gui window. The solution is to use the terminal (not the R console!) to commit changes and push:

git add *  

git commit -m "yourmessage"  

git push

2 Contributing using Visual Studio Code

You need to have Docker or Podman installed and the Dev Containers extension in VS Code. See the dev container documentation for more details.

R, Quarto, and all required extensions are pre-installed inside the container, so you do not need to set up anything else.

Open the repository folder in VS Code.
When prompted, click “Reopen in Container” (or run the command Dev Containers: Reopen in Container).
Wait for the container to build and start. This may take a few minutes on the first run.
Edit the local version as you wish.
To preview your changes locally, run quarto preview in the terminal. This opens the site in your browser.

2.1 Linting tools

The container includes two linters you can run from the terminal.

Check for typos:

typos

Fix typos automatically:

typos -w

Check Markdown formatting:

markdownlint-cli2 "**/*.qmd" "**/*.md"

Fix Markdown formatting automatically:

markdownlint-cli2 --fix "**/*.qmd" "**/*.md"

3 General Information

3.1 Adding new content

The website is organized into sections. Each section is a directory with an index.qmd landing page:

Directory	Section	Content
`people/`	People	Joining and leaving the lab, lab meeting, coffee, writing and presenting, funding
`mri/`	MRI	Running MRI studies, the DICOM to GLM pipeline (`mri/dicom-to-glm/`), tools
`behavioral/`	Behavioral	Vision tests, BIDS for behavioral data
`resources/`	Resources	Neurodesktop, power analysis, participant compensation, gamma correction, chin rests, this guide
`internship/`	Internships	Internship checklist, Pflichtpraktikum, project list
`archive/`	Archive	Outdated pages that are kept for reference

To add a page, create a new directory inside the matching section: <section>/<topic>/. Put your .qmd file in it, and put its images in <section>/<topic>/images/. Start the file with metadata like this:

---
title: "<Page title>"
description: "<One sentence that says what this page is about>"
author: <your initials>
categories: [<Category>]
date: <YYYY-MM-DD>
image: images/<preview>.png   # optional, shown on the section's cards
---

3.1.1 Naming files

Use short, descriptive, lowercase names with hyphens for pages, folders and images, for example mri/dicom-to-glm/04-defacing.qmd or images/trigger-box-settings.jpg.

3.2 Making changes visible

A new page appears on the website only after you add it in two places:

The sidebar: in _quarto.yml, add the path of your page under the sidebar of its section (for example below id: mri), in the subsection where it belongs.
The section cards: in the section’s index.qmd (for example mri/index.qmd), add the path of your page to the contents of the matching listing.