Skip to main content

Prepare your GitHub repository for Notebook.link

This guide will help you make a GitHub repository Notebook.link ready.

Notebook.link can be used to serve GitHub repositories content, allowing you to easily share your Notebooks with tutorials, classes content, live documentation etc.

Repository size limit​

The GitHub repository size is limited to 50MB, make sure your repository does not exceed this limit.

Define the environment​

Notebook.link requires that you provide the environment definition needed to run notebooks contained in the GitHub repository. See the Environment creation documentation for available features and limitations.

tip

The environment.yml file must be placed in one of these locations:

  • .nblink/environment.yml
  • Repository root (/environment.yml)

Provide a lock file​

In order to make your environment more stable through time, you can provide a lock file to make sure the packages versions are pinned.

Such a lock file content can be generated from the Environment Creation page by providing your environment.yml content, then click on the "Copy" button to get the lock content. This should be saved as a nblink-lock.json or .nblink/nblink-lock.json file in the repository.

Alternatively, the MambaJS CLI can be used. MambaJS provides a CLI that can be used from your local machine (either Linux, Windows or MacOS) to generate the lock file given the environment.yml definition of your environment. It can be installed with either pip or conda/mamba/rattler/micromamba:

pip install mambajs

# OR

conda install -c conda-forge mambajs

Then the mambajs CLI can generate a lock file as follows:

mambajs create-lock environment.yml nblink-lock.json

# OR if the environment.yml is under the .nblink directory:

mambajs create-lock .nblink/environment.yml .nblink/nblink-lock.json

Then the lock file can be commited to the repository, Notebook.link will take it into account.

note

Notebook.link can detect if the environment.yml file has changed since the last time the lock was updated, in that case it will solve the environment again and discard the lock content, considering it outdated.

Custom JupyterLite configuration​

It's also possible to provide your own JupyterLite runtime config using the jupyter-lite.json file, located either at the root or inside the .nblink directory. This can be useful if you'd like to disable some labextensions.

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "appName": "My Amazing Notebook.link demo",
    "disabledExtensions": ["@jupyterlab/application-extension:logo"]
  }
}

Read the jupyterlite documentation for more information.

Private GitHub repositories​

It is possible to expose links to your private repositories by installing the Notebook.link GitHub app on your GitHub account.

This application has access to your private repositories content, and can expose their content through shared links.

danger

Be mindful that after installing this app, anyone with a Notebook link pointing to your private repository will be able to see and download its content.

note

Once installed, you can only create links by commit hash. Read more about how to create links.