Contribute to Neurodesk.org

This applies if you wish to submit a new tutorial or amend content on a page. Our website is mostly written in Markdown (.md files). We include the basics of writing in Markdown on this page.

Table of contents

• Create your own copy of neurodesk/neurodesk.github.io repository
• Create your content or make your modifications
• Contribute your new content to the official documentation
• Formatting guidelines
• Code blocks
• Images
• Alerts and warnings
• Tables
• Lists

Create your own copy of neurodesk/neurodesk.github.io repository where you will be able to make modifications

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.”

---

Create your content or make your modifications

1. Clone your forked version of our documentation to a location of your choice on your computer.

This step is the same for macOS, Windows, and Linux.

Using SSH

git clone --recurse-submodules git@github.com:neurodesk/neurodesk.github.io.git

Using HTTPS

git clone --recurse-submodules https://github.com/neurodesk/neurodesk.github.io.git

If you cloned without —recurse-submodules

Run the following command to pull submodules:

git submodule update --init --recursive --remote

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

2. Now, you can open your copy of neurodesk.github.io using the editor of your choice (we recommend VS Code). Before making changes to the current repository, the best practice is to create a new branch to avoid version conflicts.

   • Create a branch:

     git branch tutorial-template

   • Check out the branch you want to use for the addition or changes you’d like to make:

     git checkout tutorial-template

   • Confirm you are in the right branch:

     git branch

   

3. Within your cloned environment, navigate to where you’d like to make your changes.

   For example, if you’d like to create new tutorial content, go to neurodesk.github.io/content/en/tutorials-examples/tutorials/ and then navigate to the subfolder you believe your tutorial belongs in (e.g. /functional_imaging).

4. Create a new, appropriately named Markdown file to house your content (e.g. for a tutorial about physiology, you might call it physio.md). Images need to be stored in the /static directory. Please mirror the same directory structure as for your Markdown files.

5. Open this file and populate it with your content. You’re also welcome to look at other tutorials already documented on our website for inspiration.

---

Contribute your new content to the official documentation

1. Once you are happy with your content, to avoid merge conflicts, rebase your branch with the main branch, which should be synced with neurodesk/neurodesk.github.io:main (on GitHub check if your repo is synced and locally checkout the main branch and run git pull).

   git rebase main

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

2. Commit all your changes and push these local commits to GitHub.

3. Navigate to your forked version of the repository on GitHub and switch branches for the one with your additions.

   

4. Now, you can preview the changes before contributing them upstream. For this, if this is your first time to run the Action build, click on the “Actions” tab and enable the Actions (“I understand my tutorials…”). You can run the workflow by clicking on each of them in the left sidebar.

   

5. Then you need to open the settings of the repository and check that Pages points to gh-pages, and when clicking on the link, the site should be there.

6. To contribute your changes, click “Compare & pull request” and then “Create pull request”.

   

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

8. Someone from the Neurodesk team will review and accept your changes, which will appear on our website soon.

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.

---

Formatting guidelines

As seen throughout this tutorial, you can embellish your text using Markdown conventions; text can be bold, italic, or strikethrough. You can also add links, and you can organise your content with headers, starting at level 2 (the page title is a level 1 header):

Level 2 heading

You can also include progressively smaller subheadings:

Level 3 heading

Some more detailed information.

Level 4 heading

Even more detailed information.

Code blocks

You can add code blocks to your content as follows:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)

Or add syntax highlighting to your code blocks:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)

Advanced code or command line formatting:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)
[4 6]

You can also add code snippets, e.g. var foo = "bar";, which will be shown inline.

---

Images

To add screenshots and images to your content, create a subfolder in /static with the same file structure as in your content Markdown file. Add your screenshot to this folder, keeping in mind that you may want to adjust your screenshot to a reasonable size before uploading. You can then embed these images in your tutorial using the following convention:

For a filename.png in a /content/en/tutorials-examples/subject/tutorial1/markdownfile.md use:

![filename](/static/...<fullpathhere>.../filename.png 'filename')

For example, EEGtut1.png in /content/en/tutorials-examples/tutorials/electrophysiology/eeg_mne-python.md would be:

![EEGtut1](/static/learning-resources/tutorials/electrophysiology/eeg_mne-python/EEGtut1.png 'EEGtut1')

---

Alerts and warnings

You can grab the reader’s attention to particularly important information with quote blocks, alerts, and warnings:

This is a quote block.

Note

This is an alert.

Note

This is an alert with a title.

Caution

This is a warning.

Warning

This is a warning with a title.

You can also segment information as follows:

---

There’s a horizontal rule above and below this.

---

Or add page information:

Note

This is a placeholder. Replace it with your own content.

---

Tables

You may want to order information in a table as follows:

Neuroscientist	Notable work	Lifetime
Santiago Ramón y Cajal	Investigations on microscopic structure of the brain	1852, 1934
Rita Levi-Montalcini	Discovery of nerve growth factor (NGF)	1909, 2012
Anne Treisman	Feature integration theory of attention	1935, 2018

---

Lists

You may want to organise information in a list as follows.

Here is an unordered list:

• Rstudio
• JASP
• SPSS

And an ordered list:

1. Collect data
2. Try to install analysis software
3. Cry a little

And an unordered task list:

• Install Neurodesktop
• Analyse data
• Take a vacation

And a “mixed” task list:

• writing
• ?
• more writing probably

And a nested list:

• EEG file extensions
  • .eeg, .vhdr, .vmrk
  • .edf
  • .bdf
  • .set, .fdt
  • .smr
• MEG file extensions
  • .ds
  • .fif
  • .sqd
  • .raw
  • .kdf

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.