Contribute to Neurodesk.org

This page walks through the process of submitting a new tutorial or amending an existing page, from forking the repository to opening a pull request.

Two companion pages cover the details:

• Local Development — install the tools and preview the site in your browser.
• Markdown Reference — the syntax and components available when writing a page.

The short version

If you have contributed to a GitHub project before, this will be familiar:

1. Fork neurodesk.github.io-astro and clone your fork.
2. Create a branch.
3. Add or edit pages under src/content/docs/, and images under public/.
4. Preview with pnpm dev.
5. Commit, push, and open a pull request.

The rest of this page explains each step.

1. Fork the repository

Begin by creating a copy of our documentation that you can edit:

1. Visit the GitHub repository for the Neurodesk documentation.
2. Fork the repository.

Why fork the repository?

You will now have your own copy of the documentation that you can alter without affecting our official documentation. You will see a panel stating “This branch is up to date with Neurodesk:main.” If someone else makes a change to the official documentation, the statement will change to reflect this. You can bring your repository up to date by clicking “Sync fork.”

2. Clone your fork

Clone your fork to a location of your choice. This step is the same on macOS, Windows, and Linux.

Using SSH:

git clone git@github.com:<your-username>/neurodesk.github.io-astro.git

Or using HTTPS:

git clone https://github.com/<your-username>/neurodesk.github.io-astro.git

The URL for the repository can be copied by clicking on the button highlighted below:

Open your copy using the editor of your choice — we recommend VS Code.

3. Create a branch

Before making changes, create a new branch so your work stays separate from main. Name it after what you are doing.

1. Create and switch to the branch in one command:

   git checkout -b tutorial-template

2. Confirm you are on it — the current branch is marked with an asterisk:

   git branch

   

4. Set up the local preview

Install the tools and start the dev server so you can see your changes as you write. Full instructions, including how to install Node.js and pnpm, are in Local Development.

Once set up, it is two commands:

pnpm install
pnpm dev

Leave the server running at http://localhost:4321 while you work; it reloads as you save.

5. Write your content

1. Navigate to where your content belongs. All pages live under src/content/docs/, and a file’s path there becomes its URL.

   For example, a new tutorial goes in src/content/docs/learning-resources/tutorials/, inside the subfolder that best fits your topic (e.g. /functional-imaging).

2. Create an appropriately named file — for a tutorial about physiology, physio.md. Use the .mdx extension instead if you want to use components such as <Steps> or <Tabs>.

3. Add frontmatter at the very top of the file:

   ---
   title: My Tutorial
   description: A short summary used for search results and social previews.
   ---

4. Write your content. See the Markdown Reference for the available syntax, and look at existing tutorials for inspiration.

5. Store any images in public/, mirroring the folder structure of your content file. Reference them without the public prefix, e.g. /learning-resources/tutorials/my-tutorial/image.png.

6. Open a pull request

1. Confirm the site still builds. This catches broken links and invalid frontmatter that the dev server tolerates:

   pnpm build

2. To avoid merge conflicts, bring your branch up to date with main (on GitHub check that your fork is synced, then locally check out main and run git pull):

   git rebase main

   You might have to resolve some merge conflicts, but VS Code makes it easy.

3. Commit your changes and push them to GitHub:

   git add .
   git commit -m "Document PhysIO tutorial"
   git push origin tutorial-template

4. Navigate to your fork on GitHub and switch to the branch with your additions.

   

5. Click “Compare & pull request”, then “Create pull request”.

   

6. Give your pull request a title (e.g. “Document PhysIO tutorial”), leave a comment briefly describing what you have done, and create it.

7. Someone from the Neurodesk team will review your changes, and they will appear on our website once merged.

Contributing without a local setup

Small changes — fixing a typo, correcting a link — can be made entirely in the GitHub web interface using the pencil icon on any page’s source file, without cloning anything. You will not get a rendered preview this way, so keep such edits small and let the reviewer check the result.

Thanks so much for taking the time to contribute content to the Neurodesk community. If you have any feedback on the process, please let us know on GitHub discussions.

Need help?

If you have questions or would like feedback before submitting:

• Open a discussion

We appreciate your contribution to the Neurodesk community and reproducible science.