Configuration

jOtter reads $XDG_CONFIG_HOME/jotter/config.toml (usually ~/.config/jotter/config.toml) once at startup. The file is optional and so is every key: anything missing takes its default. A typo or an unknown key is not silently ignored: jOtter starts with all defaults and shows a warning in the status line.

Defaults

A complete file with every key at its default value:

max_image_rows = 18
max_math_rows = 4
max_output_rows = 15
autosave_secs = 30
theme = "base16-ocean.dark"
editor = "builtin"
nvim_user_config = true
jedi = false
complete_on_dot = true
signature_help = true
recolor_plots = true
formatter = "ruff format -"
format_on_save = false

Options

max_image_rows

Type: integer · Default: 18

Images taller than this many terminal rows are scaled down to fit, once, when the output is first shown. Larger values show plots bigger but push the next cell further down.

max_math_rows

Type: integer · Default: 4

Display math taller than this many terminal rows is scaled down to fit: $$…$$ in markdown, latex cells, and LaTeX outputs such as SymPy’s. Inline $…$ math always takes one row. See math.

max_output_rows

Type: integer · Default: 15

Outputs taller than this many rows are shown in a scrollable viewport instead of in full. Scroll it with [ and ] or the mouse wheel; see long outputs.

autosave_secs

Type: integer · Default: 30

How often, in seconds, jOtter writes an autosave when there are unsaved changes. Autosaves go to ~/.local/state/jotter/autosave/, never next to the notebook; see data safety. Values below 1 count as 1.

theme

Type: string · Default: "base16-ocean.dark"

The syntax-highlighting theme for code cells and fenced code in markdown. One of base16-ocean.dark, base16-ocean.light, base16-eighties.dark, base16-mocha.dark, InspiredGitHub, Solarized (dark) or Solarized (light).

On a light terminal background, use base16-ocean.light, InspiredGitHub or Solarized (light). See them all in the theme gallery.

editor

Type: string · Default: "builtin"

The cell editor: "builtin", jOtter’s own vim-style editor, or "nvim", an embedded Neovim with your config and plugins that gives you the full Neovim editing model. The Neovim backend is experimental; see embedded Neovim. If Neovim is missing or crashes, jOtter falls back to the builtin editor.

nvim_user_config

Type: boolean · Default: true

With editor = "nvim": load your Neovim config and plugins. jOtter sets g:jotter = 1 before your config runs, so you can skip plugins that make no sense inside a cell. Set to false for a clean Neovim (-u NONE).

jedi

Type: boolean · Default: false

Python kernels: use IPython’s Jedi completer for every completion. Jedi completes names from code that hasn’t run yet, but is slow. When false, jOtter uses IPython’s fast completer and asks Jedi only when the fast one finds nothing; see completion.

complete_on_dot

Type: boolean · Default: true

Open completion automatically when you type . after a name. When false, completion opens only with Tab.

signature_help

Type: boolean · Default: true

Show the signature of the function you are calling, in a popup under the line, with the argument you are typing highlighted. It opens when you type ( after a name and follows the cursor through the call. The kernel only knows functions that exist, so a function from a cell that hasn’t run shows nothing. See completion.

recolor_plots

Type: boolean · Default: true

Show plots in your terminal’s colours: a figure’s white background becomes the terminal background and black text and axes become the terminal foreground, while coloured lines keep their hue. Only the display changes; the notebook, its saved outputs and files written with savefig keep their original colours. It applies to images with a large white background and no transparency, so photos and figures you styled yourself are left alone. See outputs.

formatter

Type: string · Default: "ruff format -"

The command that formats a code cell with f (or every code cell with F). It gets the cell’s source on standard input and must print the formatted source on standard output. It runs through sh in the notebook’s directory, so pipelines such as isort - | black -q - work and your project’s formatter settings (pyproject.toml, ruff.toml) apply. If it fails, for example on a syntax error, the cell is left as it was. See formatting for commands for other formatters and languages.

format_on_save

Type: boolean · Default: false

Format every code cell with formatter each time you save with w, W or :w. Autosaves don’t format.