mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
3a9c631526
While doing https://github.com/jupyterhub/jupyterhub/pull/2726, I realized we don't have a consistent way to format references inside the docs. I now have them be formatted to match the name of the file, but using `:` to separate them instead of `/` or `-`. `/` makes it ambiguous when using with markdown link syntax, as it could be a reference or a file. And using `-` is ambiguous, as that can be the name of the file itself. This PR does about half, I can do the other half later (unless someone else does).
92 lines
3.6 KiB
Markdown
92 lines
3.6 KiB
Markdown
(howto:templates)=
|
|
|
|
# Working with templates and UI
|
|
|
|
The pages of the JupyterHub application are generated from
|
|
[Jinja](https://jinja.palletsprojects.com) templates. These allow the header, for
|
|
example, to be defined once and incorporated into all pages. By providing
|
|
your own template(s), you can have complete control over JupyterHub's
|
|
appearance.
|
|
|
|
## Custom Templates
|
|
|
|
JupyterHub will look for custom templates in all paths included in the
|
|
`JupyterHub.template_paths` configuration option, falling back on these
|
|
[default templates](https://github.com/jupyterhub/jupyterhub/tree/HEAD/share/jupyterhub/templates)
|
|
if no custom template(s) with specified name(s) are found. This fallback
|
|
behavior is new in version 0.9; previous versions searched only the paths
|
|
explicitly included in `template_paths`. You may override as many
|
|
or as few templates as you desire.
|
|
|
|
## Extending Templates
|
|
|
|
Jinja provides a mechanism to [extend templates](https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance).
|
|
|
|
A base template can define `block`(s) within itself that child templates can fill up or
|
|
supply content to. The
|
|
[JupyterHub default templates](https://github.com/jupyterhub/jupyterhub/tree/HEAD/share/jupyterhub/templates)
|
|
make extensive use of blocks, thus allowing you to customize parts of the
|
|
interface easily.
|
|
|
|
In general, a child template can extend a base template, `page.html`, by beginning with:
|
|
|
|
```html
|
|
{% extends "page.html" %}
|
|
```
|
|
|
|
This works, unless you are trying to extend the default template for the same
|
|
file name. Starting in version 0.9, you may refer to the base file with a
|
|
`templates/` prefix. Thus, if you are writing a custom `page.html`, start the
|
|
file with this block:
|
|
|
|
```html
|
|
{% extends "templates/page.html" %}
|
|
```
|
|
|
|
By defining `block`s with the same name as in the base template, child templates
|
|
can replace those sections with custom content. The content from the base
|
|
template can be included in the child template with the `{{ super() }}` directive.
|
|
|
|
### Example
|
|
|
|
To add an additional message to the spawn-pending page, below the existing
|
|
text about the server starting up, place the content below in a file named
|
|
`spawn_pending.html`. This directory must also be included in the
|
|
`JupyterHub.template_paths` configuration option.
|
|
|
|
```html
|
|
{% extends "templates/spawn_pending.html" %} {% block message %} {{ super() }}
|
|
<p>Patience is a virtue.</p>
|
|
{% endblock %}
|
|
```
|
|
|
|
## Page Announcements
|
|
|
|
To add announcements to be displayed on a page, you have two options:
|
|
|
|
- [Extend the page templates as described above](#extending-templates)
|
|
- Use configuration variables
|
|
|
|
### Announcement Configuration Variables
|
|
|
|
If you set the configuration variable `JupyterHub.template_vars = {'announcement': 'some_text'}`, the given `some_text` will be placed on
|
|
the top of all pages. The more specific variables
|
|
`announcement_login`, `announcement_spawn`, `announcement_home`, and
|
|
`announcement_logout` are more specific and only show on their
|
|
respective pages (overriding the global `announcement` variable).
|
|
Note that changing these variables requires a restart, unlike direct
|
|
template extension.
|
|
|
|
Alternatively, you can get the same effect by extending templates, which allows you
|
|
to update the messages without restarting. Set
|
|
`c.JupyterHub.template_paths` as mentioned above, and then create a
|
|
template (for example, `login.html`) with:
|
|
|
|
```html
|
|
{% extends "templates/login.html" %} {% set announcement = 'some message' %}
|
|
```
|
|
|
|
Extending `page.html` puts the message on all pages, but note that
|
|
extending `page.html` takes precedence over an extension of a specific
|
|
page (unlike the variable-based approach above).
|