docs: add Jupyter Gallery configuration page - #219
Open
viniciusdc wants to merge 2 commits into
Open
Conversation
Documents the current jupyterlab-gallery setup: exhibits must live in a jupyter_gallery_config.py on the singleuser config path (injected via singleuser.extraFiles), since GalleryManager only exists in the singleuser server and hub.extraConfig silently no-ops (#134). Covers the exhibit schema and the remote-icon trap: an exhibit whose icon is a remote URL fails to load on restricted-egress clusters with no fallback, so locked-down deployments should point icon at a local, same-origin asset. Notes that a first-class singleuser.gallery values key (#118) would supersede this workaround, so the page is scoped to be replaced once that lands. Closes #218.
Contributor
|
Docs preview for |
kcpevey
reviewed
Aug 18, 2026
| | `nebi` | The companion Nebi service — image, external/internal URLs, namespace, release name | | ||
| | `rbac.bootstrap` | One-shot Keycloak Job that adds the groups-claim mapper and the shared-mount client role | | ||
| | `jupyterhub` | Passed through verbatim to the `jupyterhub` subchart (proxy, hub, singleuser images, auth, etc.) | | ||
| | Jupyter Gallery | Curated tutorial tiles in JupyterLab, configured via `jupyterhub.singleuser.extraFiles`. See [Jupyter Gallery](/gallery/) | |
There was a problem hiding this comment.
Suggested change
| | Jupyter Gallery | Curated tutorial tiles in JupyterLab, configured via `jupyterhub.singleuser.extraFiles`. See [Jupyter Gallery](/gallery/) | | |
| | Jupyter Gallery | Curated gallery tiles in JupyterLab, configured via `jupyterhub.singleuser.extraFiles`. See [Jupyter Gallery](/gallery/) | |
They aren't necessary tutorials.
| @@ -0,0 +1,101 @@ | |||
| --- | |||
| title: Jupyter Gallery | |||
| description: Configure jupyterlab-gallery exhibits, where the config has to live, and the remote-icon trap on restricted-egress clusters. | |||
There was a problem hiding this comment.
Suggested change
| description: Configure jupyterlab-gallery exhibits, where the config has to live, and the remote-icon trap on restricted-egress clusters. | |
| description: Configure jupyterlab-gallery exhibits |
I don't know what a remote-icon trap is so I wanted to remove it from the description until it can be explained later, but when I did that, the where the config has to live didn't make sense to keep.
| extension shows a curated set of tutorial "exhibits" as tiles inside | ||
| JupyterLab, each backed by a git repository the user can clone with one click. | ||
| The extension already ships in the singleuser image, so configuring it is only | ||
| a matter of telling the `GalleryManager` which exhibits to show. |
There was a problem hiding this comment.
Suggested change
| a matter of telling the `GalleryManager` which exhibits to show. | |
| a matter of telling the `GalleryManager` which exhibits to show. If not exhibits are included in the config, the section remains empty. |
| The extension already ships in the singleuser image, so configuring it is only | ||
| a matter of telling the `GalleryManager` which exhibits to show. | ||
|
|
||
| ## Where the config has to live |
There was a problem hiding this comment.
Suggested change
| ## Where the config has to live | |
| ## Location of the configuration |
| ``` | ||
|
|
||
| `destination` is the directory (relative to the user's home) that exhibits are | ||
| cloned into. |
There was a problem hiding this comment.
Suggested change
| cloned into. | |
| cloned into. The example above will clone into `$HOME/tutorials/xarray-tutorial`. |
| ## Exhibit schema | ||
|
|
||
| Each entry in `c.GalleryManager.exhibits` is a dict. The keys the upstream | ||
| `GalleryManager` understands: |
There was a problem hiding this comment.
Suggested change
| `GalleryManager` understands: | |
| `GalleryManager` accepts: |
| Each entry in `c.GalleryManager.exhibits` is a dict. The keys the upstream | ||
| `GalleryManager` understands: | ||
|
|
||
| | Key | Purpose | |
| |---|---| | ||
| | `git` | Clone URL of the exhibit repository (required) | | ||
| | `title` | Label shown on the tile | | ||
| | `homepage` | Link opened from the tile's "info" affordance | |
There was a problem hiding this comment.
Suggested change
| | `homepage` | Link opened from the tile's "info" affordance | | |
| | `homepage` | Link opened from the tile's "info" button | |
Is that what "affordance" means?
| | `icon` | Tile image (see [Tile icons](#tile-icons-and-the-remote-icon-trap) below) | | ||
| | `branch` | Branch to clone (defaults to the repo's default branch) | | ||
| | `depth` | Clone depth for shallow clones | | ||
| | `account` / `token` | Credentials for private repositories | |
There was a problem hiding this comment.
I didn't realize this was a thing. Reading this, I still don't know how to use it. Is this saying that I need two separate entries for account and token? Or is it either/or? And I assume I'd use a PAT for token, but what does account mean? Is that username?
I see the paragraph below, but I think it needs a bit more information.
There was a problem hiding this comment.
Suggested change
| | `account` / `token` | Credentials for private repositories | | |
| | `account` / `token` | Credentials for private repositories (see information below) | |
|
|
||
| For private repositories, supply `account` and a personal access `token`. | ||
| Rather than embedding the token literally in the config, reference it from an | ||
| environment variable set on the singleuser pod (for example via |
There was a problem hiding this comment.
How do I actually set this on my deployment? Its something I have to manually set a the k8s level? Will I lose it if I upgrade NIC?
This was referenced Aug 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Jupyter Gallery page to the docs site, closing #218.
Documents the current reality on
main: exhibits have to live in ajupyter_gallery_config.pyon the singleuser config path, injected viasingleuser.extraFiles.GalleryManageronly exists in the singleuser server, so putting it underhub.extraConfigsilently no-ops (that was #134).The page covers three things:
singleuser.extraFilessnippet.git,title,homepage,description,icon,branch,depth, andaccount/tokenfor private repos, with the PAT-via-env-var note pointing at the upstream README).iconis a remote URL fails to load on air-gapped / restricted-egress clusters and leaves a broken-image placeholder with no fallback. The recommendation is to pointiconat a local, same-origin asset on those deployments.I scoped the page deliberately as a workaround doc. #118 proposes a first-class
singleuser.galleryvalues key that removes the hand-rolled config file entirely; if it lands, this page collapses to the values key. There's a "Looking ahead" section that says exactly that so we don't ossify around the workaround. I'm about to run a full review on #118 separately to see if we can just unblock it.Also adds the page to the Guides sidebar and a row in the configuration reference table.