Adding content: notebook, files and static assets#

Content with the CLI#

With the CLI installed, run:

jupyter lite build

Any contents found in:

  • {lite-dir}/files/

  • any content roots added via:

    • the CLI flag --contents

    • the #/LiteBuildConfig/contents in jupyter_lite_config.json

Will be:

  • copied to the built site under {output-dir}/files/

    • may have timestamps changed if --source-date-epoch is provided.

  • indexed to provide {output-dir}/api/contents/{subdir?}/all.json

  • named in jupyter-lite.json as contentsAllJsonFile, which is what makes the frontend read the index

Note

If contents are added after the build, set contentsAllJsonFile yourself. The build only writes it when files/ exists at build time; without it no index is read, no request is made and the file browser is silently empty.

Server Contents and Local Contents#

When a user changes a server-hosted file, a copy will be made to the browser’s storage, usually in IndexedDB. A user’s locally-modified copy will take precedence over any server contents, even if the server contents are newer.

Customizing Content Storage#

By default, all of a user’s contents on the same domain will be available to all JupyterLite instances hosted there. To create separate content stores, change the jupyter-lite.json#jupyter-config-data/contentsStorageName from the default of JupyterLite Storage - <baseUrl>.

By default, the best available, persistent storage driver will be used. One may force a particular set of drivers to try with jupyter-lite.json#jupyter-config-data/contentsStorageDrivers. See more about local storage drivers.

Customizing MIME types#

MIME types drive a great number of JupyterLab’s (and therefore JupyterLite’s) features. When uploaded as pre-indexed contents, the build process will usually detect MIME types correctly.

In the browser, things are a bit trickier: a number of well-known file types (including everything needed to serve a core JupyterLite site) will be automatically detected when they are uploaded, but some customization might be required.

Any file types configured via #/LiteBuildConfig/extra_file_types will be merged with the default types into jupyter-lite.json#jupyter-config-data/fileTypes, and these will be used.

Note

These will not impact how the JupyterLite UI actually displays files: these are provided by MIME renderer plugins, such as those listed on PyPI

For example, to ensure the .fasta file format is served correctly as text/plain: jupyter_lite_config.json:

{
  "LiteBuildConfig": {
    "extra_file_types": {
      "fasta": {
        "name": "fasta",
        "extensions": [".fasta"],
        "mimeTypes": ["text/plain"],
        "fileFormat": "text"
      }
    }
  }
}

Hidden Files#

Files and directories that start with . are considered hidden, and by default will not be

  • indexed by the jupyter_server.ContentsManager which handles building Jupyter Contents API responses

  • displayed in the File Browser

To ignore these files entirely from being copied or indexed, provide the following for e.g. files in the .binder folder:

{
  "LiteBuildConfig": {
    "extra_ignore_contents": ["/\\.binder/"]
  }
}

To include these files in the output, add the following to jupyter_lite_config.json:

{
  "ContentsManager": {
    "allow_hidden": true
  }
}

Note

If included, users will be able to open these files directly:

  • clicking links to the file in files that are not hidden

  • via the Open from Path… JupyterLab command

  • from within kernels that support unified contents like the default python kernel

Showing Hidden Files#

To make hidden files visible by default in the file browser, add the following to overrides.json:

{
  "@jupyterlab/filebrowser-extension:browser": {
    "showHiddenFiles": true
  }
}