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. Esc or a click outside closes it; from a screen an area opened, Esc steps 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.

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.

Edit this page on GitHub