Prepare your Git repository for Notebook.link

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

Notebook.link can be used to serve the content of Git repositories hosted on supported Git providers, allowing you to easily share your Notebooks with tutorials, classes content, live documentation etc.

Everything in this guide applies to all Git providers, unless stated otherwise in the provider-specific sections.

Repository size limit

The 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 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 committed 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.

Updating your repository

What a link shows after you push new commits depends on the git reference it points to:

• No reference (e.g. https://notebook.link/github/{owner}/{repo}/): follows the latest commit of the default branch.
• A branch: follows the latest commit of that branch.
• A pull/merge request: follows the latest commit of that request.
• A tag or a commit hash: always shows that snapshot, whatever you push later.

Use a commit hash, together with a lock file, when you need a link whose content and environment never change. Read more about how to create links.

note

Repository content is stored in the browser cache. When a link now points to a newer commit than on a user's last visit, Notebook.link asks them whether to remove their cached data and reload the new content. Confirming discards their local modifications.

Supported Git providers

Notebook.link currently supports the following Git providers:

• GitHub
• GitLab

tip

Notebook.link queries the Git provider API to find the commit a branch, tag or pull/merge request points to. If the provider API rate limit is exceeded, use a link with a commit hash instead: it is loaded without querying the API.

GitHub

GitHub links follow the GitHub URL structure:

Reference	Link
Default branch	https://notebook.link/github/{owner}/{repo}/
Branch	https://notebook.link/github/{owner}/{repo}/tree/{branch}/
Commit	https://notebook.link/github/{owner}/{repo}/commit/{sha}/
Tag	https://notebook.link/github/{owner}/{repo}/releases/tag/{tag}/
Pull request	https://notebook.link/github/{owner}/{repo}/tree/refs/pull/{number}/head/

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.

GitLab

warning

Only public repositories hosted on gitlab.com are supported. Private repositories and self-hosted GitLab instances cannot be used yet.

GitLab links follow the GitLab URL structure, where /-/ separates the project path from the git reference. Projects in nested groups are supported:

Reference	Link
Default branch	https://notebook.link/gitlab/{group}/{project}/
Nested groups	https://notebook.link/gitlab/{group}/{subgroup}/{project}/
Branch	https://notebook.link/gitlab/{group}/{project}/-/tree/{branch}/
Commit	https://notebook.link/gitlab/{group}/{project}/-/commit/{sha}/
Tag	https://notebook.link/gitlab/{group}/{project}/-/tags/{tag}/
Merge request	https://notebook.link/gitlab/{group}/{project}/-/merge_requests/{number}/

Branch names containing slashes (e.g. feature/my-branch) are supported.