NeuroLibre is at an alpha stage of development, and is not currently open for submissions.

πŸ—‚ Preprint repository structure

We expect to find all the submission material in a public GitHub repository that has the following structure:

β”œβ”€β”€ binder
β”‚ β”œβ”€β”€ requirements.txt
β”‚ └── (data_requirement.json)
β”œβ”€β”€ content
β”‚ β”œβ”€β”€ _toc.yml
β”‚ β”œβ”€β”€ _config.yml
β”‚ β”œβ”€β”€ 01-simple_notebook.ipynb
β”‚ └── (…)
β”œβ”€β”€ paper.md
└── paper.bib

Our meta anlaysis on myelin submission which is publicly available in this github repository should help you understand the layout.


If RoboNeuro does not see this file layout, it will fail to build the jupyter book build (but may be able to build the computing environment). Make sure that your file layout never change during runtime (especially if using a Dockerfile).

⏩ Quickstart: Preprint templates

To give you a head-start, we created preprint template repositories:


Programming language

GitHub repository







To use them, make sure to read the following steps:

  1. Choose your template from the list below and create a new repository into your (or to an organization) account.

  2. Follow the instructions in the README file.

The following section provides further detail about the structure of a NeuroLibre preprint repository.

1. πŸ“ The binder folder


1.1 βš™οΈ Runtime

1.1.1 Preprint-specific runtime dependencies

The execution runtime can be based on any of the (non-proprietary) programming languages supported by Jupyter. NeuroLibre looks at the binder folder to find some configuration files such as a requirements.txt (Python), R.install (R), Project.toml (Julia) or a Dockerfile.

See also

The full list of supported configuration files is available here.

1.1.2 Environment configuration for NeuroLibre

You should try to make your environment clean and concize, that is why the preferred configuration file for NeuroLibre are the requirements.txt.

It should be small (to keep environment building and loading as short as possible), and versionnized (so your environment is fully reproducible, and cache-able).

For example this requirement is bad because it has lot of unnecessary dependencies:


On the other hand, this one is concise, reproducible and will take much less time to build:



Starting from pip 20.3, the package resolver changed its behaviour to reduce inconsistencies in software versions. As a consequence and if your submission has lot of interdependent dependencies, your build may take a while. This is typically the case if you see messages like this during the build:

INFO: pip is looking at multiple versions of linkify-it-py to determine which version is compatible with other requirements. This could take a while.


Make sure that your whole environment is not too big (<1GB of installed dependencies), and installation is fast (<10min). Large environments increase the binder spawn time, impact your computing performance, and takes a lot of space on our servers.


If your binder build fails with timeout errors, this is because your environment is too complex and slow to build. But thanks to Docker internal caching mechanism, you can still re-try to submit the same repository so it catch-up the build.

1.1.3 NeuroLibre dependencies

Our test server creates a virtual environment in which your content is re-executed to build a Jupyter Book. To enable this, we need some Python packages.

If you are using configuration files, we need latest version of jupyter-book in a requirements.txt file:

(if applicable) repo2data

1.2 πŸ’½ Data

NeuroLibre offers generous data storage and caching to supercharge your preprint. If your executable content consumes input data, you need to read this section carefully. Indeed, we don’t allow data download other than through our method.

To download data, NeuroLibre looks for a repo2data configuration file: data_requirement.json. This file must point to a publicly available dataset, so it can be available during preprint runtime.

See also

Repo2data can download data from several resources including OSF, datalad, zenodo or aws. For details, please visit the documentation.

Example preprint templates using repo2data for caching data on NeuroLibre servers:

Download Resource

GitHub repository






RoboNeuro may fail downloading relatively large datasets (exceeding 5GB) or if the data server is to slow. This is because of some limitations, independent from us, in our software stack. If you face some problems when downloading your data, please create an issue in your github repository so a Neurolibre admin can check it.

1. πŸ“ The content folder


2.1 Executable & narrative content

NeuroLibre accepts the following file types to create a preprint that is beyond PDF:

  • βœ… Jupyter Notebooks,

  • βœ… MyST formatted markdown.

  • βœ… Plain text markdown files.

  • βœ… A mixture of all above


❌ We don’t accept markdown files with narrative content only, that is not really beyond PDF :)


βœ… You can organize your content in sub-folders.

2.1.1 Writing narrative content

Jupyter Book provides you with an arsenal of authoring tools to include citations, equations, figures, special content blocks and more into your notebooks or markdown files.

See also

Please visit the corresponding Jupyter Book documentation page for guidelines.

2.1.2 Writing executable content

Based on the powerful Jupyter ecosystem, NeuroLibre preprints allow you to interleave computational material with your narrative. You can add some directives and metadata to your code cell blocks for Jupyter Book to determine the format and behavior of the outputs, such as interactive data visualization.

See also

Please visit the corresponding Jupyter Book documentation page for guidelines.

There are two mandatory files that we look for in the content folder: _config.yml and _toc.yml. These files help RoboNeuro structure your book and configure some settings.

2.2 ⑆ Table of contents

The _toc.yml file determines the structure of your NeuroLibre preprint. It is a simple configuration file specifying a table of content from all the executable & narrative content found in the content folder (and in subfolders).

See also

The complete reference for the _toc.yml can be found here.

2.3 ⚑︎ Book configuration

The _config.yml file governs all the configuration options for your Jupyter Book formatted preprint, such as adding a logo, enable/disable interactive buttons or control notebook execution and caching settings. Few important points:

  • Please ensure that the title and the list of authors matches those specified in the paper.md.

title:  "NeuroLibre preprint template"  # Add your title
author: John Doe, Jane Doe  # Add author names
  • Please ensure that the repository address is accurate.

  url: https://github.com/username/reponame  # The URL to your repository
  • By default NeuroLibre force the notebook execution, still make sure you have it enabled.

      execute_notebooks: force

See also

The complete reference for the _config.yml can be found here.

1. πŸ“ Static summary


The front matter of paper.md is used to collect meta-information about your preprint:

title: 'White matter integrity of developing brain in everlasting childhood'
  - Tag1
  - Tag2
  - name: Peter Pan
    orcid: 0000-0000-0000-0000
    affiliation: "1, 2"
  - name: Tinker Bell
    affiliation: 2
- name: Fairy dust research lab, Everyoung state university, Nevermind, Neverland
  index: 1
- name: Captain Hook's lantern, Pirate academy, Nevermind, Neverland
  index: 2
date: 08 September 1991
bibliography: paper.bib

The corpus of this static document is intended for a big picture summary of the preprint generated by the executable and narrative content you provided (in the content) folder. You can include citations to this document from an accompanying BibTex bibliography file paper.bib.

To check if your PDF compiles, visit RoboNeuro preprint preview page, select NeuroLibre PDF option and enter your repository address.

See also

For more information on how to format your paper, please take a look at JOSS documentation.