Configuration¶

Noctiluca reads one TOML file: noctiluca/config.toml in your config directory.

--config PATH reads another file. With no file, Noctiluca uses its defaults; a file named with --config must exist.

A TOML syntax error stops Noctiluca with the line. Anything else it does not understand (an unknown table or key, a value of the wrong kind) is a warning, never an error, so an old config still opens. The first warnings show on the status line when it starts; noctiluca keys prints them all.

The crate has a documented sample with every table, config.sample.toml.

[startup]
home = "https://docs.rs"
view = "projection"

[search]
url = "https://html.duckduckgo.com/html/?q={}"

[shortcuts]
gh = "https://github.com/search?q={}"
wiki = { search = "https://en.wikipedia.org/w/index.php?search={}", home = "https://en.wikipedia.org" }

[keys]
preset = "vim"
hints = "f ctrl+g"

[media]
audio = false
images = "auto"

[profile]
# name = "work"

[site."github.com"]
view = "reader"
keyword = "s"

[site."github.com".keys]
n = "scroll.down"
"]" = { role = "link", name = "Next" }

The command line wins over the file: --reader over [startup] view, --images over [media] images, --profile over [profile] name, and --audio turns sound on even when the file says false.

[startup]¶

[search]¶

[shortcuts]¶

Keywords, over the built-ins (rs, crates, mdn, gh). Each key is a keyword, and its value is one of:

See Keywords.

[keys]¶

noctiluca keys lists the ids. A line with an unknown action or a key name Noctiluca does not know is a warning, and only that line is skipped (see Your own keys).

[media]¶

[adapt]¶

Each terminal adaptation by its name, true or false:

[adapt]
collapse-nav = false
text-over-pictures = true

Every rule is on by default but text-over-pictures, which changes what a page means. --adapt and --no-adapt override this for one run.

[profile]¶

[agent]¶

The control socket for scripts and coding agents, and where Ctrl+G sends. See Scripts and coding agents.

[site."…"]: per-site settings¶

A [site."PATTERN"] table applies to the pages it matches. The pattern is a host (github.com), a wildcard (*.example.com: the domain and every host under it) or an address prefix ("https://example.com/docs/"). When several match, the most specific wins: a prefix, then a host, then a wildcard, and a longer one over a shorter. Only one table applies to a page.

The settings apply when a new page of the site opens.

[site."…".keys]¶

Each key is one key name, and its value is what it runs:

Roles are the accessibility tree's: link, button, textbox, searchbox, checkbox, switch, radio, combobox, listbox, slider, spinbutton, tab and menuitem. Ctrl+K in Noctiluca writes these lines for you, keeping the file's comments and layout. See Keys on one site.

Other files¶

Noctiluca keeps its data in its data directory: $XDG_DATA_HOME/noctiluca (else ~/.local/share/noctiluca) on Linux, ~/Library/Application Support/noctiluca on macOS, %LOCALAPPDATA%\noctiluca on Windows.

• bookmarks.toml: your bookmarks, written only when you add or remove one.
• profiles/NAME/: a kept profile.