dashboard.toml: Dashboard Settings

dashboard.toml

Configuration for the dashboard.

Defines the pages and categories that appears on the home page and navigation bar.

categories

Type: dict[string, object].

Categories for the dashboard pages, keyed by unique keys.

categories.{key}

Type: object.

Dashboard category. Appears on the home page and the navigation bar.

Note that a category entry also supports linking to a page. However, this link will only show up in the navigation bar, not on the homepage.

categories.{key}.name

Type: string.

Human-readable name of the entry.

categories.{key}.url

Type: string | null.

URL path of the entry, or None if not a link.

If entry_point is defined, this will be the URL the page will be served at. If not provided, will be determined automatically by using the key of the category and page, i.e. {category_key}/{page_key}.

Otherwise this can be any URL pointing to an internal or external resource. In that case it applies the following rules to determine how to handle the URL:

• If the URL starts with http:// or https://, it’s considered an absolute URL.

• If the URL starts with a /, it’s considered an absolute path on the current domain.

• Otherwise the URL is considered relative to the dashboard base URL, which is useful for linking to specific dashboard pages.

The URL supports the following placeholders. All placeholders have a leading /, but no trailing /.

• {base_url}: Base URL for the JupyterHub user, e.g. /user/<username>.

• {dashboard_base_url}: See dashboard_base_url().

• {filebrowser_base_url}: See filebrowser_base_url().

• {jupyterlab_base_url}: See jupyterlab_base_url().

• {vscode_base_url}: See vscode_base_url().

• {influxdb2_base_url}: See influxdb2_base_url().

categories.{key}.image

Type: string | null.

Optional image for the entry.

Must be of the form importable.module:filepath, where filepath is the path to the image file relative to the module. For example, my_module.static:images/my_image.png.

Don’t forget to include the image file in the package data of your package, see for example https://setuptools.pypa.io/en/latest/userguide/datafiles.html for how to do this using setuptools.

categories.{key}.entry_point

Type: string | null.

Object reference to the function that instantiates the page this entry links to.

Also referred to as the “entry point”. This function will be called to instantiate the page that this entry refers to. Must be of the form importable.module:callable.

categories.{key}.description

Type: string | null.

Optional description of the entry, shown on the homepage.

categories.{key}.order

Type: integer. Default: 100.

Order of the entry in the navigation bar and home page.

Lower numbers appear first.

categories.{key}.new_tab

Type: boolean. Default: False.

Whether to open the link in a new tab.

categories.{key}.pages

Type: dict[string, object].

Sub-pages under this category, keyed by unique keys.

categories.{key}.pages.{key}

Type: object.

Dashboard page entry. Appears on the homepage and the navigation bar.

categories.{key}.pages.{key}.name

Type: string.

Human-readable name of the entry.

categories.{key}.pages.{key}.url

Type: string | null.

URL path of the entry, or None if not a link.

If entry_point is defined, this will be the URL the page will be served at. If not provided, will be determined automatically by using the key of the category and page, i.e. {category_key}/{page_key}.

Otherwise this can be any URL pointing to an internal or external resource. In that case it applies the following rules to determine how to handle the URL:

• If the URL starts with http:// or https://, it’s considered an absolute URL.

• If the URL starts with a /, it’s considered an absolute path on the current domain.

• Otherwise the URL is considered relative to the dashboard base URL, which is useful for linking to specific dashboard pages.

The URL supports the following placeholders. All placeholders have a leading /, but no trailing /.

• {base_url}: Base URL for the JupyterHub user, e.g. /user/<username>.

• {dashboard_base_url}: See dashboard_base_url().

• {filebrowser_base_url}: See filebrowser_base_url().

• {jupyterlab_base_url}: See jupyterlab_base_url().

• {vscode_base_url}: See vscode_base_url().

• {influxdb2_base_url}: See influxdb2_base_url().

categories.{key}.pages.{key}.image

Type: string | null.

Optional image for the entry.

Must be of the form importable.module:filepath, where filepath is the path to the image file relative to the module. For example, my_module.static:images/my_image.png.

Don’t forget to include the image file in the package data of your package, see for example https://setuptools.pypa.io/en/latest/userguide/datafiles.html for how to do this using setuptools.

categories.{key}.pages.{key}.entry_point

Type: string | null.

Object reference to the function that instantiates the page this entry links to.

Also referred to as the “entry point”. This function will be called to instantiate the page that this entry refers to. Must be of the form importable.module:callable.

categories.{key}.pages.{key}.description

Type: string | null.

Optional description of the entry, shown on the homepage.

categories.{key}.pages.{key}.order

Type: integer. Default: 100.

Order of the entry in the navigation bar and home page.

Lower numbers appear first.

categories.{key}.pages.{key}.new_tab

Type: boolean. Default: False.

Whether to open the link in a new tab.