# Customizing RISE
## What to configure
Here's a list of things that can be customized. [See below for more
details](#how-to-customize) on how to implement those settings.
* [presentation theme](#choosing-a-theme)
* [transiton between slides ](#choosing-a-transition)
* [auto-launch presentation mode](#automatically-launch-rise)
* [where to start the presentation](#choosing-where-the-slideshow-begins)
* [automatic selection of cells](#select-cells-based-on-the-current-slide)
* [slide sizes](#change-the-width-and-height-of-slides)
* [decoration (header/footer/background)](#decorating-all-slides)
* [vertical scrollbar](#enable-a-right-scroll-bar)
* [chalkboard capabilities](#enable-chalkboard-capabilities)
* [using a leap motion controller](#usage-with-leap-motion)
* [native `reveal.js` settings](#reveal-js-configuration-options)
* [custom CSS](#adding-custom-css)
* [keyboard shortcuts](#keyboard-shortcuts-and-jupyter-actions)
### Choosing a theme
You can configure the `theme` of your presentation (which controls the
general look and feel of the presentation) with:
{
...
"rise": {"theme": "sky"}
}
### Choosing a transition
The transition configuration defines what happens in between slides:
{
...
"rise": {"transition": "zoom"}
}
### Automatically launch RISE
You can setup your notebook to start immediately with the slideshow
view using the `autolaunch` config option. This typically is very
helpful if you plan on publishing slideshows through something like
`mybinder.org`:
{
...
"rise": {"autolaunch": true}
}
### Choosing where the slideshow begins
The following configuration changes where the slides begin. By default, RISE
will start at the selected slide. To have it start at the first slide
instead, use this configuration:
{
...
"rise": {"start_slideshow_at": "beginning"}
}
### Select cells based on the current slide
As you progress into your slideshow, you either move to a new
(sub)slide, or show (or hide) a new fragment; whenever any of these
events occur, you may wish to have the jupyter selection keep in sync or
not; this is the purpose of the auto-select feature.
There are currently two settings that let you change the way auto-select
behaves, here are their default values:
{
...
"rise": {"auto_select": "code",
"auto_select_fragment": true}
}
`auto_select` can be any of:
- `code` (the first code cell is auto-selected)
- `none` (no auto-selection)
- `first` (the first cell is auto-selected)
`auto_select_fragment` is a boolean that states whether auto-selection
should select cells based on the current slide as a whole (when set to
`false`) or restrict to the current fragment (when set to `true`, the
default).
**These settings are experimental and may change in the future**;
hopefully the current default behaviour is just fine. We might remove
`auto_select_fragment` as a setting altogether; we might also turn
`auto_select` into a mere boolean, since the current setting
`auto_select = "first"` has not proved of any practical value.
Regardless, it seems like the most meaningful combinations as of now
are either `auto_select = "none"` - in which case the other setting is
ignored, or `auto_select = "code"` and `auto_select_fragment = true`,
which now is the default.
### Change the width and height of slides
To control the width and height of your slides, use the following
configuration:
{
...
"rise": {"width": "90%",
"height": "90%"}
}
**Notes**
* remember that you can always use your browser's shortcuts to zoom
in/out (`Cmd/Ctrl +` and `Cmd/Ctrl -`), and this way adjust the slide
content to your screen/projector size.
* this method is *often preferable* than setting sizes. In particular
it is dangerous to set sizes in pixels, as most often you cannot
rehearse with the actual projector. We recommend setting relative
sizes (in percents) rather than absolute ones (in `px` or `cm`).
* in any case you may want to increase the slide height to ensure that
cell outputs fit within a single slide; keep in mind that cell
contents tend to take more space as you run your code.
### Decorating all slides
RISE offers two levels for inserting a static background. You can either
* define `overlay`, in which case you take full control,
* **or** you can define `header`, `footer` and `backimage`.
So if you define `overlay`, the 3 latter options will be ignored.
#### `overlay`
It is possible to add the config option `overlay` to build a constant
background. It is wrapped in a`
`, so it can be text or html. In
this case, the user is entirely responsible for styling. For example:
{
...
"rise": {
"overlay": ""
}
}
#### `header`, `footer` and `backimage`
As a more limited, but often more convenient alternative, you can
define any of the following 3 settings.
In this case, minimal styling is applied (floor and ceiling), but user
is still responsible for cosmetic styling:
{
...
"rise": {
"backimage": "mybackimage.png",
"header": "
Hello
",
"footer": "World!
"
}
}
You can see some examples using these options at
`RISE/examples/overlay.ipynb` and
`RISE/examples/header-footer.ipynb``, or in binder respectively
[![](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/damianavila/RISE/master?filepath=examples%2Foverlay.ipynb)
[![](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/damianavila/RISE/master?filepath=examples%2Fheader-footer.ipynb)
### Enable a right scroll bar
To enable a right scroll bar when your content exceeds the slide vertical height,
use the following configuration:
{
...
"rise": {"scroll": true}
}
### Enable chalkboard capabilities
Starting RISE 5.4.1, we provide some new chalkboard capabilities.
To enable them, use the following configuration:
{
...
"rise": {"enable_chalkboard": true}
}
When enabled, this plugin adds two buttons next to the help button.
The first one provides you with a black board.
The second one allows you to draw **on top** of the current slide.
It also reacts to the following additional keyboard commands:
* `[` to turn the whole space into an empty chalkboard
* `]` to start adding free drawings to the current slide
* `\` to download chalkboard drawing
* `=` to reset chalkboard drawing on the current slide
* `-` to clear the chalkboard
### Usage with Leap Motion
**Reveal.js** supports the [Leap Motion](https://www.leapmotion.com) controller.
To control RISE slides with the Leap, put the
[reveal leap plugin options](https://github.com/hakimel/reveal.js#leap-motion)
in your config with the following parameters:
{
...
"rise": {
"leap_motion": {
"naturalSwipe" : true, # Invert swipe gestures
"pointerOpacity": 0.5, # Set pointer opacity to 0.5
"pointerColor" : "#d80000" # Red pointer"nat.png"
}
}
}
To disable it:
{
...
"rise": {
"leap_motion": "none"
}
}
### `reveal.js` configuration options
`reveal.js` offers a few configuration of its own, [as described in
`reveal.js`'s documentation](https://github.com/hakimel/reveal.js). Out of this
category, RISE will pass through the following settings:
* `controls` to enable or disable the lower right navigation arrows
* `progress` to enable or disable the thin progress bar at the bottom
of the slideshow
* `slideNumber` that allows you to turn off, or customize, slide
numbers. Set to boolean `false` to turn off, [see `reveal.js`'s doc
for more details](https://github.com/hakimel/reveal.js#slide-number)
* as well as `history`.
### Adding custom CSS
RISE looks for two css files to apply CSS changes on top of the
slideshow view:
* First, it attemps to load `rise.css`, and hence this will be
applied to all notebooks in the current directory;
* Second, it attempts to load `the_notebook_name.css` and so this will
hence be only applied to `the_notebook_name.ipynb`.
Both files need to be placed alongside with the notebook of interest,
i.e. in the same directory. You can see some examples using this
customization with `RISE/examples/showflow.ipynb`.
**NOTE.** The implementation of this feature is rather rough, both css
files are blindly included without checking for their existence, which
may result in error messages in your browser console, complaining
about `No such file or directory`. These messages can be safely
ignored. See also about
this.
***
## How to customize
RISE can be customized in a lot of ways. As of RISE version 5.3, you can:
1. use `nbextensions_configurator`; this tool offers an interactive
way to enable, disable and tweak all notebook extensions - see
screenshot below;
1. define settings [in JSON files,
typically by using python scripts](customize.html#using-python);
1. you can also embed settings in a specific notebook's metadata;
1. and you can also provide your own css file(s), that can supersede
styling of the various DOM pieces.
### The configurator
You may need to install and enable additional modules, refer to [this github
repo](https://github.com/ipython-contrib/jupyter_contrib_nbextensions) for more
details on Jupyter notebook extensions.
In a nutshell:
pip3 install jupyter_contrib_nbextensions
jupyter contrib nbextension install
or
conda install -c conda-forge jupyter_nbextensions_configurator
You should then see a fourth tab in jupyter's directory views, as
depicted below. Settings are stored in JSON format, typically in
~/.jupyter/nbconfig/notebook.json
![](../examples/configurator.png)
### Using python
As an alternative way, you can tweak your local user's settings with a
script rather than from the configurator. For example you can use
python like shown in this example below, that leverages the JSON config
manager from `traitlets`:
```python
#!/usr/bin/env python3
from traitlets.config.manager import BaseJSONConfigManager
from pathlib import Path
path = Path.home() / ".jupyter" / "nbconfig"
cm = BaseJSONConfigManager(config_dir=str(path))
cm.update(
"rise",
{
"theme": "sky",
"transition": "zoom",
"start_slideshow_at": "selected",
}
)
```
**Notes:**
* the `config_dir` parameter should point at where the `nbconfig` is
located. This will vary depending on your setup, and specifically on
where you "installed" and "enabled" the nbextension.
* running the example above would result in the creation (or
modification) of a file named `~/.jupyter/rise.json`, which is
generally the right place to store user preferences,
* to adjust this path to your own setup, you can use `jupyter
--paths`, and specifically the `config` section, to see the path
locations that are applicable.
* for more information, see these docs:
*
* .
### Notebook metadata
These settings can also be stored in your notebook metadata, which
holds a JSON object, that can be edited through Jupyter's standard
menu (Edit → Edit Notebook Metadata); typically it would look like
this:
{
...
"rise": {
"theme": "serif",
"transition": "zoom",
...
},
...
}
You can edit notebook metadata as follows
![](../examples/metadata.png)
### Note on legacy naming
For the remaining of this section, let us forget about custom CSS for
a while, and concentrate on the first 3 configuration methods :
configurator, JSON files, and notebook metadata.
In all this document we refer to settings stored in a JSON key or
filename `rise`. You may also see some notebooks using the
`livereveal` key instead, which is an older name for the same
project. FOr backward compatibility, both names are actually taken
into account, however you should know that `rise` will take precedence
on `livereveal` if the same setting in defined under both names.
You are encouraged to always use the `rise` naming as much as possible.
### Order of precedence
The order of precedence between these 3 sources of configuration is as
follows:
* a setting defined in the notebook's metadata is always valid; among
these, as described above, settings in the `rise` category will
override those defined in `livereveal` if both entries apply;
* if still undefined, a setting defined in the configurator will be valid;
Finally, the following priorities apply:
* if still undefined, a setting defined in any of the JSON files
considered by your jupyter server will be taken into account. Here
again, `rise.json` supersedes `livereveal.json` in case of an overlap.
Apart from that, the scope of what is configurable through these
various channels (configurator, JSON and metadata) is
identical, so it is possible to use the configurator as some sort of
an online reference manual, as it describes each and every setting.
### Local setting vs hosted infrastructure
At this point you need to be aware that:
* settings changed through the configurator or JSON files - are stored
on your own file system, typically in your home directory, and so
are only be applicable to people using this notebook server;
generally it is used for user preferences or such.
* *a contrario* settings embedded in a specific notebook's metadata
will be applicable to all users that get their hands on that notebook,
even if they end up in a mybinder instance via github.
****
## Keyboard shortcuts and Jupyter actions
Here are the Jupyter actions registered by RISE:
action name key behaviour
------------------------------------------------------
RISE:slideshow alt-r enter/exit RISE Slideshow
RISE:smart-exec execute cell, move to the next if on same slide
RISE:toggle-slide shift-i (un)set current cell as a Slide cell
RISE:toggle-subslide shift-b (un)set current cell as a Sub-slide cell
RISE:toggle-fragment shift-g (un)set current cell as a Fragment cell
RISE:toggle-notes (un)set current cell as a Notes cell
RISE:toggle-skip (un)set current cell as a Skip cell
RISE:render-all-cells render all cells (all cells go to command mode)
RISE:edit-all-cells edit all cells (all cells go to edit mode)
RISE:rise-nbconfigurator shift-c open the nbconfigurator pane in another tab
Some, but not all, come bound to default keyboard shortcuts. There are
2 ways you can change the bindings
### Through JSON
Like the other settings described in this section, you can define
shortcuts in JSON with e.g.
{
...
"rise": {
"shortcuts": {
"slideshow": "alt-a",
"edit-all-cells": "ctrl-e"
}
}
With the above settings, RISE would **not** bind the default `Alt-R`
key to `RISE:slideshow`, but it would bind `Alt-A` instead. It would
also bind `RISE:edit-all-cells` to `Ctrl-e`.
### Through `custom.js`
You can also use these actions in some regular javascript code,
typically your `~/.jupyter/custom/custom.js`. Here is an example that
will attach one of these actions to a custom keyboard shortcut:
```javascript
define(
['base/js/namespace'],
function(Jupyter) {
let command_shortcuts = Jupyter.keyboard_manager.command_shortcuts;
// set / unset the 'Slide' tag in slideshow metadata
command_shortcuts.set_shortcut(
'alt-a', 'RISE:slideshow');
})
```
Note that with this approach, you will end up with the
`RISE:slideshow` action bound to **both** `Alt-R` and `Alt-A`.
### Keyboard shortcut editors
The actions exposed to Jupyter are also present in Jupyter's
mainstream keyboard shortcuts editor, that you can use to (un)define
your custom shortcuts.