This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contribute Tutorials and Example Notebooks

A brief guide for contributing new tutorials and example notebooks.

Neurodesk welcomes community-contributed content. We aim to collect a wide variety of tutorials and examples representing the spectrum of tools available under the Neurodesk architecture and the diversity in how researchers might apply them. Sharing your expertise helps others learn and supports reproducible research.

  • A tutorial: Markdown-based, concise step-by-step documentation integrated into the website, for using specific neuroimaging software on neurodesk with screenshots for visual aid
  • An example notebook: Jupyter notebooks that illustrate tool usage or analysis pipelines are stored in a separate repository. These notebooks can be interactive and are ideal for showcasing scripts, visualizations, or code-driven workflows.

How to Contribute

To contribute a new tutorial or example notebook:

  1. Start from the template
    Use the tutorial template or the example notebook template as a starting point. They include recommended formatting and structure.

  2. Follow the documentation style
    Write clearly and concisely. Include any necessary prerequisites, commands, and expected outputs.

    • Tutorials should use Markdown with well-formatted headings, lists, and code blocks
    • Notebooks should be well-commented and executable from start to finish

  3. Save your content

  4. Submit your contribution

    • Open a pull request to the appropriate repository
    • Include a brief summary of what your tutorial or notebook covers
    • Check that any links, figures, or code blocks are working and properly rendered

Tips for Good Tutorials

  • Focus on a specific tool or workflow
  • Include sample commands and outputs
  • Keep it as reproducible by using open dataset
  • Link to any relevant containers, documentation, or datasets

Attribution

We credit all tutorial contributors on the Contributors page.
If you would like to be listed, please include your name and a short description in your pull request, following this format.

In addition, each example notebook receives a DOI for formal attribution through Zenodo. This ensures that your contribution is citable and can be referenced in academic publications.

Need Help?

If you have questions or would like feedback before submitting, feel free to open a discussion.

Thank you for helping build a more accessible and collaborative neuroimaging community.

1 - Contribute Example Notebooks

A brief guide for contributing new example notebooks.

We welcome example notebooks that demonstrate how to use tools within Neurodesk. These notebooks serve as valuable learning resources and promote reproducible workflows across the neuroimaging community.

Example notebooks are hosted in the neurodesk/example-notebooks repository and are intended to be lightweight, self-contained, and easy to follow.

Getting Started

To contribute a new notebook, follow the steps below:

1. Start from the template

Use the official example notebook template as a starting point. It includes guidance on formatting, structure, metadata, and citation instructions.

Each notebook should contain:

  • A clear title and short description
  • An overview of the tool or workflow demonstrated
  • The container/tool version used
  • Code cells with explanatory comments
  • Example data (or guidance on how to access it)

2. Follow best practices

  • Keep notebooks self-contained and executable top to bottom. Before being published, a Github Action will confirm the Notebook is working.
  • Avoid hardcoded file paths where possible
  • Use publicly accessible datasets
  • Include inline comments and Markdown cells for explanation

For more detail, consult the README in the example-notebooks repository.

Saving and Submitting

  1. Add your completed notebook to the appropriate folder under:

    /books/

  2. Open a pull request in the example-notebooks repository

  3. In your pull request, include:

    • A short description of your notebook
    • Any dependencies or expected output

Attribution

All notebook contributors are acknowledged on the Neurodesk Contributors page.
Please include your name and a short description in your pull request using this format.

Each example notebook receives a DOI for formal citation via Zenodo, ensuring your work is citable in academic contexts.

Need Help?

If you have questions or would like feedback before submitting:

We look forward to your contributions and thank you for supporting open and reproducible neuroimaging.

2 - Contribute Tutorials

A brief guide for contributing new tutorials.

We welcome tutorials that walk users through using tools or workflows available in Neurodesk. These tutorials are valuable learning resources that support accessible, reproducible neuroimaging.

Tutorials are written in Markdown and hosted in the neurodesk.github.io:tutorials repository, where they appear as part of the documentation site.

Getting Started

To contribute a new tutorial, follow the steps below:

1. Start from the template

Download the tutorial Markdown template file from GitHub and edit it locally with your own content.

The template includes:

  • A frontmatter block with title, linkTitle, description, and other metadata
  • A placeholder author attribution block
  • Section headings and content structure for a clear tutorial layout

2. Follow best practices

  • Use clear, descriptive section headers
  • Include step-by-step instructions with commands and screenshots
  • Store images in the appropriate /static/ folder and link them with full paths
  • Write in plain Markdown, using Hugo formatting where needed

See existing tutorial examples for reference.

Saving and Submitting

Follow the steps for contributing content to Neurodesk.org

  1. Place your completed .md file in the appropriate subfolder under:

    /content/en/tutorials-examples/tutorials/

  2. Store any images in a matching subfolder in /static/tutorials-examples/tutorials/

  3. Open a pull request in the neurodesk.github.io repository

  4. In your pull request, include:

    • A short summary of your tutorial
    • Your name and GitHub handle (if you’d like to be credited)

Attribution

All tutorial contributors are acknowledged on the Contributors page.
To be listed, include your name and a short description in your pull request using this format.

Need Help?

If you have questions or would like feedback before submitting:

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