Settings reference
Three levels. Library settings travel with the folder
(<library>/.niman/settings.json, hand-editable, unknown keys
preserved). How a library looks on this screen — the tree’s width, the
text size, the editor and its toggles — is per library too, but kept on
the device, so a phone and a desktop each keep their own. App settings
(language, theme, layout, debug log) stay on the device for every
library.
The Settings screen
Settings is split into areas, grouped by what they change: App (appearance, themes, editor, keyboard shortcuts, commands, text recognition, export, updates, diagnostics), the open Library (features, folders, journal, study, navigation, trash and history, sync, transcription, reminders), and Maintenance (re-index, rebuild the index, switch or close the library; in the settings window only the first two, since the rail’s library window switches and closes). Rebuilding deletes the library’s index file and reads every note into a fresh one — the repair for an index a full disk or an interrupted update left unreadable, which a re-index over the same file could not fix. The library itself is untouched: it stays on the list, with what was open in it, its settings and its sync. The search at the top looks through the settings themselves, not only the area names, and takes you to the row it found.
- Wide windows (desktop and tablets; a phone is not one, in landscape
or not): Settings
opens as a floating window over the note, from the gear at the foot of
the rail or its key, and closes back to it. The note, its tabs and the
tree stay where they were.
Escor a click outside closes it; from a screen an area opened,Escsteps back first. Inside are two columns: the search and the areas on the left, the selected area on the right, so nothing navigates. What an area opens, such as the toolbar arrangement or the trash, stays in the window with a way back. A search result shows its row on the right and flashes it; the results stay, one click from the next. The window is at most 960 × 680 and shrinks with a small window. - Phones, upright or turned: the list of areas, each opening a screen of its own.
Every setting reads the same on both: its name, a line saying what it does, and the control under that. A switch flips in place; anything with more than two choices shows its current value in a field that opens the choices: a drop-down under the field on a desktop, a dialog on a phone (#712). A size or a width is a slider: in the row itself on a desktop, the value at its end and kept when you let go; in a dialog on a phone.
Features
Settings → Library → Features, the group’s first row, switches the macro features of the open library on and off: search, quick note, templates, web capture, todo, journal, calendar, the note kinds, the PDF and EPUB readers, annotations, text recognition, Home and the Android widgets. Four presets (Everything, Writing, Notes only, Tasks & journal) set the switches in one tap. An area of a feature that is off is not listed here, nor found by the search at the top (Reminders goes only when Todo and Calendar are both off). Nothing in the library’s files is changed by a switch. The whole story is in features.md.
Navigation
Settings → Navigation orders the phone’s bottom bar and the desktop’s rail, and hides the destinations you do not use: drag a row by its handle to move it, flip its switch to hide it. The same entries mean different things on a wide window: Files, Search (and the tag tree behind it) and Study are sidebar views — they swap what the left panel shows while the open notes and the right panel stay — and Home and Todo are content destinations, opening as a tab in the focused pane with the tree still beside them (platforms). Settings cannot be hidden (it shows a lock), but it can be moved; the rail keeps it at its foot with the library switcher either way. At least one destination besides Settings stays shown: its switch is off-limits while it is the last one. The bar or the rail under or beside the list is a preview of the result.
Study starts hidden: a library with no flashcards has no use for it. The first deck made offers to show it, once; its switch here shows it any time.
A destination whose feature is switched off in Features stays in this list, greyed, Off in this library, with Off in Features › where its switch was; nothing is written to the layout for it, so turning the feature on restores what you had.
A hidden destination is still in the command palette (Go to: …). On a phone it opens as a page, with a back arrow to where you were; on the desktop the rail simply has nothing selected.
Opens on picks the destination the app opens on: where a library opens, and where the app comes back to after a restart. Any destination shown can be it but Settings and the quick note (a note, not a place); without a choice it is Files. Hiding it makes the app open on Files again — or, with Files hidden too, on the first destination shown — and the row says which; showing it again brings the choice back. Something that names a destination of its own still wins: a widget, a notification, a shared item, a reminder, the palette. The back arrow of a hidden destination whose way back has been hidden since returns to it too.
The layout belongs to the library and travels with it. Only on this device detaches it: the device keeps its own copy, starting from what it shows, and the library’s is left as it was; back on This library, the device drops its copy and follows the library again.
Library settings (LibraryConfig)
These describe the library itself, and travel with it (and with the
sync) in .niman/settings.json.
| Key | Default | Meaning |
|---|---|---|
trashEnabled |
true | Deletes move to .trash/; false = hard delete |
trashAutoEmptyDays |
0 (= never) | Days an item waits in .trash/ before the library opening deletes it for good (1–3650; anything else reads as never) |
historyVersions |
10 | Kept .history/ versions per note (0–100, 0 = none) |
historyIntervalMinutes |
5 | Least minutes between two versions kept while editing (1–60) |
quickNotePath |
null (= Quick note.md at root) |
Quick-note target, library-relative |
listNoteFolder |
Lists |
Where new list notes go |
templateFolder |
Templates |
Where note templates live |
attachmentsFolder |
assets |
Where copied-in images and voice clips live, under the library root |
annotationsFolder |
Annotations |
Where a note annotating a PDF or a book is made, when the file has none yet (see organization) |
captureFolder |
Clippings |
Where a web page or a quote captured as a new note goes (Settings → Folders and paths → Web captures folder), whatever newItemLocation says; the capture can still pick another folder for one page. Its pictures go in attachmentsFolder (see web capture) |
highlightColour |
yellow |
The colour a passage of a PDF or a book is highlighted in: the one last chosen (yellow, green, blue, pink; see organization) |
linkType |
wikilink |
What the link button inserts (wikilink or markdown) |
exportFolder |
system |
Where an export’s save dialog opens (Settings → Folders and paths → Export folder, #1286): system (wherever the system opens it) or library (this library’s folder); see export for what each platform’s dialog takes |
linkUpdate |
automatic |
What a rename or a move does to the links other notes hold to what moved (Settings → Editor → Update links after rename or move): automatic rewrites them, ask asks once per move how many notes would change and rewrites on a yes, never leaves them as written. History, reading positions, settings and the Home follow the move whichever it is (see links) |
weekStart |
system |
The day every calendar starts the week on (Settings → Appearance → First day of the week): system — the system’s region’s first day, not the app language’s (on Linux LC_ALL, LC_TIME, LANG; on Windows the region settings’ first day) — or monday, saturday, sunday, the same on every device of the library |
newItemLocation |
openNoteFolder |
Where new notes and folders go (Settings → Editor → New notes and folders go to): libraryRoot, or openNoteFolder — the folder of the note open at the time, the library root while none is open. One rule for a new note, a new folder, new slides, a voice note, the quick note’s create, a note from a template, the note a dead link creates and a shared text file imported as a note; the Files view’s own New (the Files FAB, the tree footer’s menu: always the library root), the tree’s Create … here, a link that names a path, the journal’s folder, list notes (listNoteFolder) and web captures (captureFolder) do not ask it (see organization). It replaced missingNoteLocation (currentFolder reads as openNoteFolder), which is read when newItemLocation is absent and no longer written |
indentWidth |
2 | Spaces per indent (2–8, clamped) |
newCardsPerDay |
20 | New flashcards each deck shows per day (Settings → Study → New cards per day; 0 = none, up to 1000, clamped). Reset all reviews there makes every card of every deck new again; no note changes |
tidyOnClose |
true | Tidy the Markdown of a note closed after an edit (Settings → Editor → Tidy the Markdown on close); notes over 4 MB are left as they are, and a type: audio note’s clip document is never tidied |
cascadeChecklist |
true | Ticking a checklist item ticks the tasks nested under it (Settings → Editor → Tick nested checkboxes); clearing a parent leaves its children as they are |
linkPreview |
true | Whether hovering a link previews the note it points at (Settings → Editor → Preview links): a card at the pointer in the read view, with Ctrl (⌘) held in the editor, and a sheet from a long press on a touch screen (see links) |
frontmatterPanel |
true | Whether a note’s frontmatter is drawn as the properties panel above it (Settings → Editor → Properties panel): closed until it is opened, away while the note is scrolled past its head. Off, a note is its own text everywhere (see frontmatter) |
lintRulesOff |
[] | The #72 rules on by default turned off, by id (tight-lists, task-marker, list-spacing, closing-fence, fence-language, join-wrapped-items, join-paragraph-lines, split-paragraph-lines), chosen in Settings → Editor → Markdown rules; a rule added in a later build runs, or not, as it ships |
lintRulesOn |
[] | The #72 rules off by default turned on, by id (hard-breaks-as-paragraphs), chosen in the same place |
spellDictionaries |
[] (= locale default) | hunspell dictionaries, selection order |
reminderShowTokens |
false | Keep +/@/# markers in reminder notifications |
journalFolder |
Journal |
Where the journal’s entries go (empty = the root) |
journalEntryName |
YYYY/MM/YYYY-MM-DD |
An entry’s name: YYYY MM M DD D, / for a folder, 'quoted' text |
journalTemplate |
none (= a heading with the date) | The template an entry is made from, library-relative |
journalDayStart |
0 | The hour a new day begins (0–6): at 4, until four in the morning is still yesterday |
journalClockTimes |
false | Read an event’s time as a clock (09:00–12:00, in the device’s zone) rather than as calendar.txt writes it (9-12); the file is never touched by it (Settings → Journal → Calendar → Event times) |
features |
none (= every feature on) | The switches that are off, by id: {"todo": false} (Settings → Features); an absent id reads as on, so a feature a later build adds is born on, and an id this build does not know is kept. Written only once a switch has been flipped (see features) |
featuresReviewed |
false | Whether the Features introduction has been through its screen: written when the screen is left, never when it opens, and synced with the library |
navigation |
none (= every destination, in the shipped order) | The bar’s and the rail’s order, hidden destinations and start (Settings → Navigation): {"order": [names], "hidden": [names], "start": name} with files, todo, search, home, quicknote, settings, where start (Opens on) is absent for Files; a destination a later build adds goes in after its default neighbour, shown, and a name this build does not know is kept |
The Diagnostics and info area also carries the first run again (#266): What Niman can do reopens the welcome deck read-only, and Take the tour runs the guided tour — resuming one left halfway, starting a finished one over. Both are device settings, like the deck’s Markdown answer themselves.
Library settings kept on this device
Per library, but in the app’s own storage rather than the folder: what
suits a desktop’s wide window does not suit a phone. The first time a
library is opened by a version with this split, the device takes these
values from settings.json; after that, it keeps its own, and they
leave the file at its next write.
| Key | Default | Meaning |
|---|---|---|
editorKind |
source |
source or wysiwyg |
enabledEditors |
both | Which editors the settings screen offers (never none) |
treeSort |
nameAsc |
Tree order and the way (nameAsc, nameDesc, modifiedAsc, modifiedDesc, createdAsc, createdDesc, sizeAsc, sizeDesc). Names order without regard to case or accents, and numbers by value: note 2 before note 10, apple before Zebra, Émile among the e’s |
treeView |
list |
How the Files pane shows a folder: list (the tree) or grid |
pinnedCollapsed |
false | Tree’s pinned section rolled up |
lineNumbers |
true | Editor row-number column |
readableLineLength |
true | Keep a note’s text in a centred column |
noteColumnWidth |
700 | That column’s text width, px (490–1400, clamped); Settings shows it as a share of 700 px (70%–200%) |
typewriter |
false | Keep the line being written in the middle of the editor |
editorAutofocus |
false | Raise the keyboard on note open |
editorToolbar |
”” (= shipped) | Arranged toolbar layout |
uiTextScale |
1.0 | Interface text size (0.8–1.8) |
noteTextScale |
1.0 | Note text size, editor + preview (0.8–1.8); the list and quote columns, the spacing, the bullets, checkboxes and numbers grow with it; also set by the zoom keys (Ctrl+=, Ctrl+-, Ctrl+0) and commands, in steps of 0.1 |
sourceFont |
monospace |
The source pane’s face (Settings → Editor → Source editor font): monospace, sansSerif or serif; the preview and live keep the note’s own face |
treeWidth |
340 | Tree pane width, px (200–600) |
dockWidth |
280 | Side panel width, px (200–600); drag its left edge |
epubTheme |
none (= the app’s) | The theme the EPUB books wear: a theme id, a shipped one or custom:… |
epubBrightness |
none (= the app’s) | The books’ brightness: system, day or night |
epubFont |
literata |
The books’ face: literata, serif, sans or mono |
epubProgress |
chapter |
What the books’ progress line shows: chapter, book or time (the time left); also set by a tap on the line |
epubTextScale |
1.0 | The books’ text size (0.8–2.5, wider than the note’s); also set by a pinch over a book and, with a book on screen, by the zoom keys and commands |
deviceNavigation |
none (= the library’s navigation) |
This device’s own navigation, same shape as navigation, set by Only on this device; while there, it wins |
The five folder keys — listNoteFolder, templateFolder,
attachmentsFolder, annotationsFolder, captureFolder — are paths
under the library root, created the first time something is written there. Their picker lists the folders
the library actually holds, so a default naming one it has never had
(assets, until an image or a voice clip is copied in) starts out
unselected: New folder then builds it at the library root, and only
nests it inside a folder you selected yourself.
A missing, unreadable, or malformed file reads as defaults — it never takes the app down. Writes are atomic (temp file + rename).
App settings (on device)
Brightness (day / night / system) and the theme the app wears are on Themes (below); UI language, last opened library, debug log toggle (default on), the keyboard shortcuts and the formatting keys, the commands pinned in the palette, and — on the desktops — Close to the tray (default on: the window’s × hides Niman and leaves it running).
Export
Settings → Export holds what an export is made on, the same for every library:
- PDF paper — the sheet a PDF export is printed on: A0, A1, A2, A3, A4 (the default), A5, Letter, Legal or Tabloid. A note prints on it standing up; a kanban board on its side when its columns fit one row of it. A slides note keeps its own 16:9 sheets. The HTML export’s page asks a printer for the same paper.
Themes
The app’s colors have their own area: Settings → Themes. Brightness — day, night, or whatever the device says — is its first row, and under it sit the themes, each with its colors in front of you: the palettes Niman ships (System, Niman, Catppuccin, Solarized, Gruvbox, Sepia) and the themes of your own.
Making one, editing its colors, renaming it, deleting it, exporting it
into a .json file and importing one back are all there. The whole story
is in themes.md; the themes do not live in the library — they
are the installation’s, so a copied folder does not carry them.
Sync
Sync → WebDAV holds the open library’s sync destination: folder
address, user, the password (in the device keychain), what the server
can do, when to sync (automatically, how often to check the server,
Wi-Fi only on phones), and Disconnect. It is per library and per device — not in
settings.json, so a copied folder never starts syncing into the
original’s server. See sync.md.
Updates
On a computer — Linux, Windows, macOS — Niman does not look for new versions and does not offer them (#1270). The Updates screen holds one row, Release page, which opens the latest release on GitHub in the browser: download the new version there and install it as you installed this one. A desktop install takes too many shapes (an AppImage run from anywhere, a tarball, a package, a setup, a disk image) for the app to replace the one that runs.
On Android, Automatic updates (default off) checks GitHub Releases
shortly after launch and then every 6 hours, quietly: a failure (offline,
no network) is a skipped check, never an error dialog. When a newer release
is found, a banner offers the download: the .apk goes into the app’s own
folder and the system installer opens, where you confirm. The first time,
Android has to let Niman install apps: the app explains it and opens the
Install unknown apps page; turn on Allow from this source, come back,
and the install goes on — without downloading again (#900). If the
installer cannot be opened, the message offers the release page instead. A
downloaded APK is cleared at the next launch.
Check for updates runs the same check on demand, and only checks: it
says whether a newer release is out, and when one is, the Download row
under it turns on. Nothing is fetched until you press it. It works even
with automatic updates off, and an update the automatic check already
found is ready to download when you open the screen.
While an update downloads, the banner (and the Download row) show how far it got; Cancel there stops it and leaves nothing behind, and a second Download is not started over one already running. Later puts the banner away for this run.
A test (beta) build has no updates of its own, on any platform: the screen says so, and the next one is installed by hand.
The Diagnostics and info section holds two read-only facts about the installation: the app’s own Version, and Changelog, which opens the full list of shipped versions, newest first. Each entry’s bullets are Markdown — their bold, code and links read as they would in a note. The same changelog appears as a dialog on the first launch after an update, listing only what is new since the version you last saw. Beside them, the Markdown cheatsheet: every construct Niman reads, written and shown (see editing); from here its examples are copied, since no note is open to insert them in.
An exported debug log starts by naming what it came from: the version and build number, the channel (release or test), the build mode and the commit it was built from, the system and its cores, the device (Android: maker, model and Android version), and every screen’s size, density and refresh rate. A log handed over for a bug or a slow screen is then comparable with the next one, and a frame time can be read against the screen’s own budget — 16.7 ms at 60 Hz, 8.3 ms at 120.