Organization: trash, history, frontmatter, tags
Trash
Deletes go to .trash/ (soft delete) or remove the file permanently
(hard delete), depending on the library’s trashEnabled setting
(default true). Restore by moving the file back out of .trash/.
Deleting a file that notes were written about — a PDF’s annotations, a scan’s recognized text — asks about them on the delete’s own question: Delete only the file, or Also delete the N notes about it. The answer you picked last is the one emphasised next time; the first time it is the one that takes them along. Taken, they are trash items of their own and the snackbar’s Undo brings the file and them back together; left, they stay where they are. Should one of the notes refuse to go, the others still do, the Undo still brings back everything that went, and the failure is reported after it. A folder offers the same — Delete or Also delete the N notes about it — for the companions living outside it (its files’ sidecars and any companions inside go with the folder itself), and a file with nothing written about it deletes without a question, as it always did.
Companions are found through the index and, so one written a moment ago is still counted, by reading the annotations folder where Niman writes them: only the notes the index does not know — or holds an older row for — are opened, so a folder the index is up to date with costs one listing and nothing more. A note opened there answers for itself in place of what the index held for it; the file’s companions elsewhere still count.
On a desktop the trash opens as a floating window over the note, so the
tree and the open note stay where they are; on a phone it is a page.
Every feature is on every platform, only the shape of it differs
(platforms.md).
Emptying it on its own. Settings → Trash and history → Auto-empty
trash is Never until you set it: pick a wait (a week, a month, a
year) and every deletion that has sat in .trash/ longer than that is
deleted for good
the next time the library opens. It happens quietly and there is no
undo, which is why nothing is deleted until you choose a wait. Only what
Niman put in the trash is counted — a file you moved into .trash/
yourself carries no deletion date and is left where it is. Empty
trash, by hand, is not that: it takes everything in .trash/, yours
included.
History
Niman keeps past versions of every note under .history/, so an edit
you regret can be undone.
When a version is kept. A version is the text a save is about to replace — never a copy of what is already on screen:
- when you start editing a note (the note as it was before you touched it);
- while you write, at most once every few minutes
(
historyIntervalMinutes, default 5); - right before a restore, before a library-wide replace, and (with sync) before a download overwrites the note;
- when a save is about to overwrite a version of the note that another program wrote since the editor last read or wrote it (changed outside Niman), whatever the interval.
A version identical to the newest one is not kept twice, and an empty note (one just created) has nothing to keep. Autosave runs every half second, so without the interval ten versions would last five seconds.
How many. The last historyVersions versions per note (default 10;
0 keeps none). Older ones are dropped as new ones arrive. Both settings
live in Settings → Trash and history and in .niman/settings.json;
out-of-range values in a hand-edited file read back as the defaults.
Browse and restore. Long-press a note in the tree (right-click on
desktop) or open the note’s ⋮ menu and pick History. Versions are
listed newest first, grouped by day, each with why it was kept and how
many lines differ from the note as it is now (+ added since, −
gone since) — the same comparison the version opens on. Open one to see what changed against
the current note (removed lines in red, added in green; tap a folded
row to show the unchanged lines) or to read its whole text. Restore
this version keeps the current text as a version first, then puts the
old one back — the snackbar’s Undo swaps them again.
On a desktop with room for the dock, History on the note on screen
opens the dock’s History pane instead, and a version there opens
beside it as a tab of the pane, note.md — 3 Oct 14:02, with the same
Changes / Version switch and Restore (#712): the note’s own tabs and
the dock stay where they are, a note tab shows the note again and the
version’s tab brings it back. A restore closes that tab and offers
Undo. All versions, at the foot of the pane, and History on
any other note open the history page.
Following the note. Renaming or moving a note (or its folder) moves
its history too, and rewrites the links other notes hold to it: a wikilink
written by path and a Markdown link follow the new path, and a wikilink
written by name follows a rename. Each link keeps the form it was written
in — a Markdown link relative to its note stays relative, so the note still
reads right in any other Markdown tool — and a link that still finds the
note as written, such as one naming only the end of its path, is left
alone. (The library can ask first, or leave the links as written: Settings →
Editor → Update links after rename or move, see links.) Open
notes are saved before the rename, and re-read after it. Embedded attachments (![[…]] and
) follow the same way, so a renamed attachments folder keeps the
pictures and clips that cited it. The settings that name a note or a folder
follow it the same way — the quick note, the list, template, attachments
and annotations folders, and the journal’s own folder and template — and so
does a home-screen note widget on Android, so a renamed folder keeps
whatever pointed inside it. A note in the trash keeps
its history until the trash is emptied or the item deleted for good; a hard
delete (trash off) removes it at once.
On disk. .history/<path>.log lists a note’s versions (time, reason,
size, hash), and .history/.objects/ holds their content, compressed,
each kept once however many notes or versions share it. Older versions
are stored as the difference from the one after them, so twenty
sessions of edits to a long note take a few percent of twenty copies.
Keeping a version adds nothing a save has to wait for on the disk: the
note is written as before, and a version a crash interrupts is simply
missing from the list. The tidying — compressing, storing differences,
removing what no note’s history names any more — runs in the background
after an editing session and when a library opens. A history kept by an
older Niman (<path>.v<n> files) moves to this form the first time it is
used, nothing lost. The folder is never indexed, searched, or synced.
Frontmatter
A note may open with a YAML block:
---
title: My note
tags: [work, urgent]
date: 2026-09-01
pinned: true
aliases: [My alias]
---
Any key is stored and filterable (key = value in search). Keys the app
acts on: title, tags, date, pinned, aliases, type (list
shows the checklist, shopping-list the same with a quantity per item,
audio shows the recordings, slides shows a deck, kanban shows a board). Everything else is your own vocabulary —
stored, searchable, but driving nothing.
pinned: true notes appear in the tree’s pinned section.
Both editors and the read pane show the block as fields, above the
note. Each puts the frontmatter at the top as one row per key — the
key in a left column, the value, and a small chip naming the type (text,
number, date, boolean, list): a text line, a number, a date, a tick for
true/false, a chip per list item. The × on a row takes one out, and
Add a property is always at hand — it is the panel’s one action, so it
stays whether the rows are showing or not. A Raw YAML toggle in the header
shows the same block as written. It is one panel everywhere, so the surfaces
cannot drift.
The panel is the note’s head, and it behaves like one. It opens closed: one row with the handle and Add a property, the fields a tap away on the handle. Scroll the note past its frontmatter and the panel steps aside — the note, not the panel, is what you scrolled to — and it comes back, as you left it, when the head is on screen again. With typewriter mode on, where the note scrolls to follow the caret, the panel follows the caret’s own line instead: it shows while the caret is on the head and steps aside once it is in the body, so the two never chase each other on a short note. A library that would rather have no panel at all turns it off in Settings › Editor › Properties panel; off, a note is its own text in both surfaces.
A date is picked, not typed: a date: field opens the platform’s own calendar,
and the file gets back the YYYY-MM-DD the parser reads as a date.
On a desktop the panel edits in place, with no dialog (#712): a click on a
value turns it into a field — Enter or a click elsewhere keeps it, Esc
leaves it — a date opens a calendar under itself (a year picked in it leaves the
calendar open for the day), a list’s + takes one
item in a field of its own, Add field asks for the key in a row and then
opens its value — or, for a key the note already has, opens that field and
changes nothing — and the type chip at the row’s end is a menu that turns the
field into another type (a list’s items joined into one value, a value made
the one item of a list). A phone keeps the dialog; there too, a key the note
already has opens that field’s own editor instead of being written over, and a
key the panel cannot show (a nested block) is refused in the dialog. A key
that is in the note with nothing after it (title:) counts as not there: adding
it fills it in.
In every surface the file is the only copy: an edit rewrites that key’s line
and leaves the rest of the block — comments, quoting, the other keys — exactly
where it was, and it saves and undoes like any other edit. The rewritten line
keeps the indentation, the &anchor an *alias points at and the comment
that follows its value (or, for a value that goes on over several lines, the
one after the key), and a key that is added joins the others at their
indentation. A comment on an item of a list that is rewritten goes with it. The fields are a second way into the same file, not a second file.
A value is shown as it is written (1.10 stays 1.10), and a value saved
unchanged writes nothing. A list’s items are edited as a comma-separated line
in YAML’s own spelling: "Doe, J", x is two items, the quotes keeping the
comma inside the first, and an item left alone keeps the YAML it had — 1 a
number, "1" text. A list holding anything a chip cannot show (a nested
mapping, an empty item) has no row and is edited in the raw YAML.
A block that does not parse shows no field rows at all: the panel says why and
shows the raw YAML, which is left as written — nothing the panel draws rewrites
a note it cannot read. A note with no frontmatter shows no panel. Keys whose
value is a nested mapping are left to the raw YAML, and the fields the panel
draws are text, number, date, true/false and lists.
Tags
Two places, both searchable:
- Frontmatter
tags(list or string). - Inline
#tagsin the note body.
Search a single tag with #tag (see search).
The tag list is behind Search’s tag button. On a wide window it is a
collapsible tree in the sidebar: #work/meetings sits under #work, and
opening a tag lists its notes under it, each with the count the tag
itself carries. A phone keeps the two-level list — every tag, then the
tag’s notes with a Back arrow.
A tag’s characters are letters and digits — any script’s, so #città and
#идея are one tag each — plus -, _ and /. The frontmatter and the note
body are read the same way, so the same tag written either way is one tag.
The tree
The tree — the left column on a wide window, the Files tab on a phone — shows one row per note and folder, folders first. The chevron at its foot (in the Files app bar on a phone) opens what it is ordered by: Name, Last modified, Date created or Size, and the way: Ascending or Descending. Choosing an order keeps the way that is on; the two entries under the divider turn it over, and the chevron tips with it. Name is A→Z, or Z→A descending; the times run oldest first and newest first; size counts bytes and smallest first and largest first — a folder’s own size is 0, and the folders keep the lead whichever field is chosen. Ties fall back to the name. The order and the way are one setting of this device, kept like the tree’s width (see settings).
The folders you have open stay open: they are kept with the library’s open notes on this device, so a restart or a switch of library finds the tree as you left it, with the folders above the open note open. Renaming or moving a folder keeps what was open under it open; deleting it forgets them.
Windows, macOS and iOS report a file’s creation time and the index records it, and a save keeps it: editing an old note does not make it new. Linux and Android do not offer one through the file API the app uses, so Date created is the modification time there — the order above it (see platforms).
A click on a folder’s row takes the keyboard — the pane is where the walk
goes on from — and the arrows then walk the rows: Home/End and
PgUp/PgDn jump, Enter opens the note (or opens the folder) the
cursor is on, ← closes an open folder or steps out to the row that holds
it, → opens a closed one or steps into the rows under it, F2 renames
and Delete deletes the row the cursor is on, and the menu key or
Shift+F10 opens its menu (the one a right click opens), anchored at the
row. A click on a note is a note
to write in: it opens and the caret goes into it, and the pane keeps no
keys a note would need — on a desktop, where the keyboard is always there
(a phone’s is the Keyboard on open setting’s). A modified key is left
to the app’s own shortcuts — Alt+←/→ walk the notes’ history and
Ctrl+Shift+PgUp/PgDn the journal — so the walk never shadows one.
On a desktop the tree also takes (#712): Ctrl+Enter opens the note
under the cursor in a new tab, and typing a name jumps to the next row that
starts with it. Several rows at once: Shift+click marks the rows from
the cursor’s to the one clicked, Shift+↑/↓ marks on from the
keyboard, Space marks or unmarks the cursor’s row, and Esc or a plain
click lets them go — as does a row leaving the tree. A right click on a
marked row opens their menu — Selected: N, Move… into one folder,
Delete — and Delete with the cursor on a marked row deletes them all;
on any other row it deletes that row alone, and the marks let go. Into the
trash, one Undo brings them all back. (A file’s own
notes stay where they are in that case: the question about them is asked
for one file at a time.) Reveal in tree, in the palette and the View
menu, shows the note on screen as the tree’s row and gives the tree the
keyboard; it has no key by default — Ctrl+Shift+E is the editor’s
inline code — and Settings → Keyboard shortcuts can give it one.
Ctrl+click keeps opening a note in a new tab.
The grid
The Files pane has a second shape: a grid of one folder’s children, as a file manager’s main pane shows them. The List | Grid pair at the tree’s foot, beside the sort chevron, switches in place — the icon of the view that is on is filled. On a phone, where the app bar has no room for the pair, the switch rides at the top of the sort menu. The view is remembered on this device, like the sort order.
Each tile is its icon, its name on up to two lines and the date of the
field the folder is sorted by: the modified day, or the created day when
Date created is the order in force — Name and Size show the
modified day. A pinned note wears a pin in its own folder; a text
recognition sidecar follows its file, dimmed with the scanner icon.
Nothing is read from disk to draw a tile — there are no thumbnails, so a
picture wears its outline icon and a large folder costs the index alone.
index.md is an ordinary note, as everywhere else.
A tap opens a note or enters a folder; Ctrl+click or a middle click
opens a note in a tab of its own. The breadcrumb above the tiles shows
the way from the library — Library › Projects › Niman; Up (also
Backspace or Alt+Up) leaves for the parent, and a crumb goes straight
to its folder. At the library’s root Up is disabled, not hidden; a narrow
pane folds the middle crumbs into a … that opens them as a menu.
Nothing else changes: the row menu (long press, right-click) is the same
one, a drag moves a tile onto another tile or a crumb as a row does, and
a rename on Linux and Windows lays the tree’s own field over the tile.
A click on a folder’s tile takes the keyboard, as a folder’s row does; a
click on a note’s opens it with the caret in it. The walk is the tree’s
own: the arrows, Home/End and PgUp/PgDn move the cursor, Enter
opens or enters, F2 renames and Delete deletes the tile the cursor is
on. A modified key stays the app’s here too.
Entering a folder writes the move through to the tree: the folder is selected and opened there, so switching back to the list finds it. The grid’s own folder lives while the library is open, not in a file: every switch to the grid starts from the tree’s selection — the folder selected, or the folder the selected note sits in — and the grid keeps that folder while it is the pane on screen.
Where new notes and folders go
One library setting, Settings → Editor → New notes and folders go to
(newItemLocation, see settings), decides where a new note
or folder is made when nothing else names the place:
- Library root — at the top level of the library.
- Folder of the open note (the default) — next to the note on screen; with no note open, at the library root. On a phone the open note is the one selected in the tree; a folder selected instead counts as none.
It is the same rule for New note, New folder, New slides and New voice note (the command palette, the tray and the keyboard shortcuts), the quick note’s create button, a note from a template, the note a dead link creates, a text file shared into Niman and imported as a note (with no note open, which is how a share usually arrives, it lands at the root), and a Home action that names no folder. Changing the setting moves all of them at once.
What does not ask the rule, because it already says where:
- The Files view’s own New — the Files FAB on a phone, the tree footer’s menu on the desktop, the rail’s New on a tablet: what it makes (a note, a folder, a voice note, slides, flashcards, a kanban board, a note from a template) goes in the library root, whatever note is open or selected in the tree. The view shows the whole library, so its New starts at the top of it; to make something inside a folder, use that folder’s menu (below).
- Create … here in a folder’s context menu, and the tree’s and the grid’s right-click menus on empty space: the note or folder goes in that folder (the library root, for the empty space of the tree). The same menus offer New voice note here, New slides here, New flashcards here and New kanban board here (#997): the kind is made right there instead of where the setting says, with the content it always starts from. The list note, the journal and a capture keep folders of their own, so none of them is on a folder’s menu.
- A link that names a path (
[[Sub/Foo]]), a template whose frontmatter names itsfolder, a Home action’s own folder, and the folder picked in a capture. - The kinds that keep a folder of their own: the journal,
New list note (
listNoteFolder) and a page or a quote captured as a new note, which goes in the web captures folder (captureFolder,Clippingsby default; see web capture). - Attachments pasted or dropped on a note, and the text note a recognition writes (always beside its file).
Renaming a note or a folder
On Linux and Windows a rename happens in the tree, as in a file manager:
Rename in a row’s right-click menu, F2 on the selected row, or
Rename in the command palette and the note’s ⋮ menu (which show the
note’s row first) turn the row’s name into a field, the name selected
without its extension — note of note.md, a folder’s whole name.
Enter or a click elsewhere renames, Esc puts the name back, and an
empty or unchanged name changes nothing. A name that cannot be used — one
another file of the folder already has, or a character the file system
refuses — leaves the field open and says why under it. A file keeps its
extension: a PDF renamed is still a PDF. With the tree hidden, and on a
phone, the rename asks for the name in a dialog. F2 can be changed under
Settings → Keyboard shortcuts.
A new note or folder is named the same way (#712): New note and New
folder — from the tree’s menus, the New button, Ctrl+N or the
palette — add a row where it will be, under its folder or at the top of
the tree, with New note or New folder selected in a field. Enter or
a click elsewhere makes it with that name (and opens a note), Esc gives
it up and nothing is made. With the tree hidden or showing the grid, and
on a phone, the name is asked in a dialog.
Moving a note or a folder
Long-press a row in the tree (right-click on desktop, or the menu key or
Shift+F10 on the row the keyboard’s cursor is on) and pick Move.
The dialog lists the library root and every folder, one radio each, the
same way the folder settings ask for a folder — and, like them, it has a
New folder button, so a note can be moved somewhere that does not
exist yet without leaving the dialog. A field at the top filters the list
as you type (any part of the path, case ignored): ↑/↓ move the choice
through what is left and Enter takes it. A folder is never offered
itself or anything inside it as a target.
Or drag the row: with the mouse on the desktop, or on a phone by holding the row and then moving the finger (held and let go without moving, the hold opens the row’s menu as before). Let go on a folder and it moves into that folder; on a note — pinned rows included — into that note’s folder; on the empty space below the rows, into the library root. The pinned block’s heading takes no drop. The row under the pointer lights up where a drop would move something — a folder dropped on itself or inside itself, or anything dropped where it already is, stays put. It is the same move as the menu’s: links follow, open notes are saved first.
A drag reaches what is out of sight (#1071): held within a row or two of the top or bottom edge of the tree (or of the folder grid), the list scrolls, faster the closer to the edge, and stops when the pointer moves back; and a drag that rests for about half a second on a closed folder in the tree opens it, so a target inside is one drop away. A folder opened that way closes again if the drop lands anywhere but in it, and stays open if it lands in it or under it.
Rows marked together (see below) are dragged together, too (#996): drag any one of them and every marked row moves, each on its own — a marked folder carries its contents, and a path inside another marked folder is not moved twice. The card under the pointer says how many rows are on their way. Dragging an unmarked row still moves that row alone.
A move of several rows (by a drop, or by the marked rows’ Move…) says at the end how many rows moved and how many could not — a row that fails does not stop the others — and writes the open notes once for all of them. A drop made while another is still moving waits for it.
Duplicating a file
Duplicate in a file’s row menu — the tree or the grid, right-click or
long press — copies the file beside itself under a free name: note.md
becomes note_1.md, and the copy appears in the tree at once. The bytes
are copied as they are, so a picture, a PDF or an audio file duplicates
whole rather than being re-encoded; a folder is not offered the action,
its tree being a copy of its own. The open notes are saved first, so the
copy holds what is on screen rather than the last autosave.
Opening a note outside Niman
A note is also a file, and sometimes you want it where Niman is not: to attach it to a mail, to drag it somewhere, to open it in another editor. Long-press a note in the tree (right-click on desktop) and pick:
- Show in file manager — opens the note’s folder with the note itself selected. On Windows that is Explorer; on Linux it is whichever file manager answers the freedesktop interface (Nautilus, Dolphin, Nemo, Thunar, …), falling back to just opening the folder when none does.
- Open in default app — hands the
.mdto whatever application the system opens Markdown with, or to the default text editor when nothing claims.md.
Both entries are desktop only (Linux and Windows) and appear on notes, not on folders. Neither changes the note or moves anything: if the file is not on disk, or the system refuses to open it, Niman says so and the note stays exactly as it was.
Files that are not notes
The tree also shows the files that are not text — the images and audio clips in the attachments folder, a PDF or an e-book dropped into the library.
- Pictures (PNG, JPEG, GIF, WebP, BMP) and PDFs open in the note pane, on every platform: a picture fitted to the pane, zoomed with a pinch or the mouse wheel and dragged around; a PDF page after page, zoomed the same way. The row under them names the file and, on desktop, offers Open in default app.
- The row under a PDF or a book has a link button: it copies a link to the place being read, to paste into a note (see links).
- A PDF or a book opens where you left it: its page, or its chapter
and the line in it, is kept for the library in
.niman/reading.jsonand syncs with it, so a book put down on the phone opens on the desktop where the phone stopped. Only reading moves it: opening a book and closing it again changes nothing. A file moved or renamed in Niman, or a folder holding it, keeps its place. A long book shows its start while the rest of it is read; if you scroll it before then, it stays where you took it instead of jumping to where you left it, and the page is not pulled back from under your finger, the wheel or the keys. A tap or a click that does not scroll it moves nothing. - A PDF on screen can be renamed, moved or deleted like any other file, on every platform — Windows included, which refuses to move a file a program still has open. The PDF lets go of its file first (the pane goes blank for a moment), and after a rename or a move it opens again at the new place; a deleted PDF closes its tab. The same goes for a folder holding an open PDF and for a voice-note clip being played (it stops); and the sync can replace, move or trash a PDF that is open.
- EPUB books open in the note pane too, on every platform, and read like a note, in the note column. The book’s own styles are not used — its headings, emphasis, lists, quotes, tables and pictures are, in Niman’s typography. The Outline button on the row below lists the book’s table of contents, the chapter being read marked, and jumps to the entry picked; a link inside the book jumps within it, a web link opens in the browser.
- Books have a look of their own, apart from the notes: the Aa button on the book’s row opens it, and so does Settings → Appearance → Book appearance, on the same values. Theme is any of the app’s themes, your own included, or Same as the app; Brightness is light, dark, the system’s, or the app’s; the font is Literata (a typeface made for reading on screen, shipped with Niman, the same on every platform), the system’s serif, the app’s own sans serif, or monospace; Text size shows on the book as the slider moves, from 80% to 250% — larger than a note goes, for a phone held at arm’s length or a reader who needs it bigger. Every choice applies at once to every book of the library, and is kept per library on this device, like the note text size. A fresh library reads its books in Literata, in the app’s colours.
- Zooming a book’s text works as it does in a note, on the same
Text size the sheet sets: pinch the book with two fingers (or a
laptop’s trackpad) — spread them to zoom in, bring them together to
zoom out — turn the mouse wheel with
Ctrlheld, or pressCtrl/⌘+=,Ctrl/⌘+-andCtrl/⌘+0(back to the normal size), in full screen too; the palette’s Zoom in, Zoom out and Reset zoom do the same while a book is on screen. The size is kept like a pick in the sheet, and stays between 80% and 250%; a note’s own text size is left alone, and still stops at 180%. - How far you have read: a line by the book’s row says it, in one of
three views a tap (or
Enteron it) moves between — the dots beside it say which: the chapter and how far into it (Chapter I · 62%), the book and which chapter of how many (38% of the book · chapter 4 of 38, its track ticked where every chapter starts), or the time left to the chapter’s end and to the book’s (Chapter ≈ 11 min · Book ≈ 5 h 40 min). On a phone it is a line of its own over the row; on a tablet and a desktop it sits in the row beside the book’s name, and a pointer resting on it shows the three at once. It follows the reading as the book scrolls, and moves at once on a jump — the contents, a link. It is measured in characters, from the top of the view, so a long paragraph weighs what it holds; the time is the words left at about 250 a minute. The view picked is kept per library with the books’ look, so the next book opens on it. - Full screen: the full-screen button on the book’s row reads it over the whole screen, its row still under it — the window goes full screen on the desktop, and the system bars step aside on Android. The same button, Esc on the desktop or Back on Android leaves it, the book still where you were reading.
- Reading a book aloud (Android, for now — see platforms): the speaker on the book’s row reads from the paragraph at the top of the view, and Read aloud from here, in the menu of a passage selected, from that paragraph. The voice is the device’s own text-to-speech, in the book’s language (the device’s when the book names none); with no voice installed for it, Niman says so and offers the system’s settings to install one, or the default voice. While it reads, a player takes the row’s place: stop, the paragraph before and after, play and pause, the speed (0.5× to 2×, a tap moves to the next) and a sheet for the voice, each with a sample. The sentence spoken is marked and the book follows it; scroll away by hand and the voice goes on, Back to the voice bringing the view back. What is read is the text — headings, paragraphs, list items, quotes; pictures, rules, code and footnote marks are skipped, a link reads as its words. A pause keeps the sentence, and play says it again; a chapter’s end goes on into the next, the book’s end stops. It goes on with the screen off and Niman in the background, under a notification with the lock screen’s controls; a call, another app’s audio or headphones unplugged pause it, and it does not resume by itself. The place kept is the one spoken. Closing the book, or swiping Niman away, stops it.
- Anything else (an audio clip, an archive) does not go in the editor: the pane says the file is not a text note, and on desktop offers Open in default app right there.
- With the readers off (Features), a PDF or a book is not shown either: the pane names the file and offers Open in default app, on every platform. Pictures are still shown.
Annotating a PDF or a book
Annotations are one of the Features, and need the readers: switched off, there is no annotating or highlighting, and the companion notes stay.
A PDF or a book is annotated in a note of its own, its companion note, without leaving the file:
- In a book, select a passage — long-press a word and drag the handles on a phone; drag with the mouse on desktop, where a double click selects a word and a triple click a paragraph — and pick Annotate in its menu; the same menu copies the text, or a link to the passage (on a phone, behind ⋮). The annotate button on the book’s row annotates the passage selected, or the paragraph at the top of the view when nothing is.
- In a PDF, select a passage and pick Annotate in its menu. The annotate button on the PDF’s row annotates the passage selected, or the page being read when nothing is — a scanned PDF has no text to select.
A sheet (a dialog on a wide window) shows the place and the passage and takes your comment, which may stay empty. Save writes it and leaves you where you were; the message that says so offers Open note, which opens the companion at the annotation.
Companion notes are ordinary notes, deleted on their own; deleting the file they annotate offers to take them along — see trash.
Each annotation is a section of the companion: a heading naming the place, the passage quoted with a link back to it, and your comment:
## Dune, p. 34
> The spice must flow.
> — [[Books/Dune.pdf#page=34&chars=120-180|Dune, p. 34]]
Remember this.
The link goes back to the passage (see links), so you can go back and forth between the file and the note. The note’s outline is the list of its annotations.
The file shows where it was annotated: in a book, the annotated paragraph is tinted as a highlighter marks it, with a dotted underline — a note is behind it; in a PDF, the passage is, and a page annotated as a whole wears a note button at its top right corner. Tap a mark to open its annotation in the companion note; where several mark the same place, a sheet asks which. The marks are read from the companion notes: edit or delete an annotation there, and the file follows.
Highlighting a PDF or a book
To mark a passage without writing about it, select it and pick Highlight in its menu — first in a book’s menu, beside Annotate in a PDF’s. It is drawn at once in the colour last chosen, yellow to start; there is nothing to fill in.
Tap a highlight for its menu: its four colours — yellow, green, blue, pink, the current one marked — Annotate, which asks for a comment and turns it into an annotation where it is, Copy, Copy link to this place, and Remove highlight. A colour picked is the one the next highlight takes. Where a highlight and an annotation cover the same words, the annotation is drawn over it and a tap asks which.
A highlight is kept in the companion note too, after the annotations written before it: the passage quoted and its link, no heading and no comment, its colour in the link —
> The spice must flow.
> — [[Books/Dune.pdf#page=34&chars=120-180&highlight=green|Dune, p. 34]]
— so it syncs with the note, and deleting the quote there removes the
highlight from the file. The colour last chosen is the library’s
highlightColour setting (see settings).
A companion is a plain note that names its file in its frontmatter,
annotates: "[[Books/Dune.pdf]]" — not by its name or its folder: it can
live anywhere and be renamed, and you can write one by hand. The first
annotation of a file that has none makes one in the annotations folder
(Settings → Folders and paths, Annotations by default), named after the
file: Dune - Annotation.md. Later ones are added at its end. A file with
several companions gets its annotations in the first, by path.
Nothing is written to such a file, ever — it is never reported as saved, because there is nothing of it in the editor to save. A picture, a PDF or a book is shown, not edited, so the editor’s controls are not offered around it: no editor/preview switch, and its ⋮ menu (on a phone) keeps the file’s own actions — rename, move, delete — without the outline, tags, typewriter, Tidy Markdown, cheatsheet or history. The palette leaves those commands out too.
Opening a file outside any library
Not every text file belongs in a library: a project’s README, a draft
from another app, a downloaded article. On Linux and Windows,
Open file (Ctrl+Shift+O, or Note: Open file… in the command
palette) opens one on its own, with Niman’s editor and nothing else. The
screen that opens a library offers the same button, so no library is
needed at all. Double-clicking a .md file in the file manager does the
same once Niman is its app (see platforms), and so does
niman <file> on the command line.
Open file filters to the text files the editor opens — .md,
.markdown and .txt, the same three a drop takes. What a library calls
a note is narrower: a note is a .md. A .txt picked from outside a
library opens on its own like any other file, and one already inside a
library is a row the editor opens, but no note is made of it: an import
copies a folder’s Markdown and leaves its .txt files where they are,
and an export carries one alongside the pages instead of writing it as
one.
The file gets the editor, both of them, and the preview. It gets none of what a library adds:
- Saved where it is, as it is. Nothing is written beside it.
- Not indexed: search, tags and backlinks never see it.
- No history, no sync, no trash.
- Links shown, not followed into a library. Its frontmatter is text:
a
type:in it draws no list. - No image button: there is no attachments folder to copy an image into. Images next to the file still show in the preview.
It opens over whatever was showing, with a thin bar naming the file and
the folder it sits in. Opening another adds a tab (Ctrl+Tab between
them, Ctrl+W closes one), and closing the last, or going back, lands
where you were. If another program changes the file while it is open,
the change comes in, unless you have unsaved edits of your own; those
win. As everywhere in Niman, edits save on their own after a pause.
A file inside the library you have open is one of its notes, and opens as one, with its history and its links. Opening it on its own would put two editors on one file.
On Android a picked file arrives as a copy that cannot be saved back, so this is not offered there yet.
Dropping files on the window
On Linux, Windows and macOS, files and folders dragged from the file manager onto Niman’s window are taken in, over whichever screen is showing. On Linux a frame around the window says so while you drag; on Windows the drop lands without it, for the reason platforms gives.
- A text file (
.md,.markdown,.txt) opens the way Open file opens one: as its note when it is inside the open library, on its own otherwise. Drop several and each opens, in a tab of its own. - A folder of the open library is shown in the tree, with the folders above it opened on the way.
- A folder from anywhere else is offered for import, and the offer says what it will make: its Markdown files copied and, when it has web pages, those converted into notes. See Importing a folder. The folder you dropped is left exactly as it was.
- A Notion export (the
.zipof Export → Markdown & CSV) is imported: see Importing a Notion export. - A book (
.epub) is offered for conversion into notes: see Converting a book into notes. With no library open, a message says one is needed. - A web page (
.html,.htm,.xhtml) opens a dialog with three choices: Convert makes a note of it (see Converting a web page into a note), Attach does what a drop of any other file does (next item), and Attach and convert does the attaching, then the converting. With no note open to take it — or a note outside the library — the two that attach stay in the dialog, greyed, with the reason under them. Drop several pages at once and the one dialog lists them all; the folder is asked once and each is converted in turn. With no library open, a page is left alone and a message names it. - With no library open, a dropped folder opens as the library, the way Open existing would open it.
- Anything else — a PDF, a picture, an archive — is attached to the note on screen: copied into the library’s attachments folder and linked where the note’s caret is, as a pasted file is. With no note open to take it (or a note outside the library), it is left alone, and a message names it.
On Android (split screen, a freeform window, Samsung DeX, ChromeOS) and on an iPad (Split View, Slide Over, Stage Manager), files dragged from another app onto Niman are taken the same way: copied first, since the other app hands over their content rather than a path, then attached to the note on screen — or, for a web page, asked about as above. A drag that carries only text is not taken there: a passage selected in a browser is text, and a page saved as a file is told from it by being only itself.
Converting a book into notes
A book in EPUB is read in the note pane like a note, and it can also
become notes of the library: editable, searchable, linkable, and exportable to another tool.
Convert to Markdown… is on the book’s own row in the reader, in the
tree’s menu on an .epub row, in the palette (Library: Convert EPUB to
Markdown…, which converts the book on screen or the one selected, and
otherwise asks for a file), in Settings → Maintenance (a book outside
the library), and it is what dropping a book on the window or sharing one
to Niman on Android does.
The dialog says what the book will make, and asks two things:
- One note per chapter (the default for a book of several) or one note of the whole book.
- Into which folder: the one the book is in, when it is in the library, otherwise the top of the library; any other can be picked.
One note per chapter makes a folder named after the book (Dune, or
Dune 2 when that is taken):
- The chapters. Each one is a note named after its entry in the
book’s contents, numbered so the tree lists them in reading order:
01 Arrakis.md,02 Muad'Dib.md. A chapter’s own sections stay headings inside its note. - Parts. A book in parts gets a folder a part, its chapters in it:
02 Book Two/03 The Storm.md. A part’s own page — its title, an epigraph — is the folder’s first note,00 Book Two.md. A part that is one long file with its chapters inside it is split at the chapters all the same. - The opening. What comes before the first chapter (a title page, a
dedication) is a note of its own,
00 Front matter.md. index.md. It carries the book’s details as frontmatter (title, author, language, publisher, date, ISBN, series, description, subjects as tags, cover), then the cover and the contents as links to the notes. These are the keys a folder’s EPUB export reads, so the folder exports back to a book with its metadata.- Pictures. They are copied into the book folder’s attachments folder
(
assets), each picture once, and the notes point at them there: the folder can be moved, and exports back as a book, with its pictures. - Links within the book. They point at the note they land in, at its heading when they land on one; links to the web stay as they were.
One note is the whole book in a single note beside the folder’s others, its pictures in the library’s attachments folder.
The conversion runs in the background. A progress dialog shows each
picture and note being written, and Cancel stops it with nothing left
in the library. When it is done, the tree shows the new folder and
index.md opens (or the one note does). The book itself stays where it
was; a shared book’s copy is deleted.
Not converted:
- a book whose text is protected (DRM), which says so;
- a file that is not an EPUB;
- a book that would expand past what the app can take in, refused before it is unpacked, as a Notion export is — or whose text is in a single file of more than 32 MiB (a novel’s is about one), which a phone could not hold once read.
Formulas come in as TeX where the book draws them as images with their TeX attached. Formulas written as MathML alone are left out, as the reader leaves them out.
Converting a web page into a note
A web page saved as a file — .html, .htm or .xhtml, what a
browser’s Save page as writes — can become a note of the library:
editable, searchable, linkable. Convert to Markdown… is in the tree’s
menu on such a row, in the palette (Library: Convert HTML to
Markdown…, which converts the page on screen or the one selected, and
otherwise asks for a file), in Settings → Maintenance (Convert an
HTML file to Markdown, for a file outside the library), and it is what
the Convert choice of a drop on the window
does, and what sharing a page to Niman, or opening it with Niman, does
on Android.
The dialog names the file and asks one thing: Into which folder — the
one the page is in, when it is in the library, otherwise the top of the
library; any other can be picked — and, for a page that is a
book, how to cut it. The note is named after
the page’s title — the article’s own, without the site’s name a <title>
often adds; with no article, the <title>, else the page’s og:title,
else its first heading, else the file’s name — and numbered like any new
note when that name is taken.
What the note holds:
- The article, not the page. As web capture does, it
keeps the article and leaves the menus, the banners and the footer out.
A page where none can be told — a list, a table, a page of a few
lines — is kept whole instead, everything between its
<body>tags. - Frontmatter.
sourceis the page’s own address, when it says one (its canonical link, elseog:url);importedis the day of the conversion;authoris there when the page names one (its author<meta>or a link marked as the author’s). The title is the note’s first heading. - Pictures. A picture beside the file (a browser’s
Page_filesfolder) is copied into the library’s attachments folder; one that is on the web is downloaded there; one written into the page itself (data:) is decoded and written there. Each picture is kept once, named by what it is, the way a pasted picture is, and the note shows it like any attachment. A picture that cannot be had keeps its web address; a local one that is missing is left out. - Links. A link to the web stays as it is. A link to another local
file stays as it was written — unless the page is converted as part of a
folder, where a link to another page of the folder
points at the note it became. A link inside the page (
#section) points at the heading it lands in. Ajavascript:link, and the like, is text, not a link.
The conversion runs in the background, with a progress dialog and Cancel, which leaves the library as it was. When it is done, the tree shows the note’s folder and the note opens. The page itself stays where it was; a shared page’s copy is deleted.
Not converted:
- a file of more than 32 MiB;
- a page whose text encoding Niman cannot read — it reads UTF-8,
UTF-16, ASCII, Latin-1 and Windows-1252, told by the file’s byte-order
mark or its
<meta charset>— which says so; - a file that cannot be read.
The limits on pictures are the web capture’s: at most 60 downloaded for a page, each under 15 MB; the ones past it keep their web address.
A page that is a book
A long page that is a book — a fanfiction downloaded from the Archive of Our Own, a novel saved from another site — becomes a folder of notes, as an EPUB does. Niman reads the page before it asks, and for a book the dialog names it, its authors and the chapters it found, and asks:
- One note per chapter (the default for a book of several) or one note of the whole book;
- Into which folder, as for any page.
A page is a book when it is an AO3 download, which Niman knows by its
shape (the preface, the chapters and the link to the work on the
Archive), or when its headings say so: the shallowest heading level
that occurs at least three times sets off the chapters, the page has at
least 20,000 characters of text, and the chapters are long — the median
one at least 2,000 characters — so that a long article with a few short
sections stays an article. Any other page is converted as a page, as
above. The page is taken whole, not reduced to its article: the preface
with the work’s details would not survive it. A line ended by a <br> is a
paragraph of its own, as an AO3 download writes them.
One note per chapter makes a folder named after the book (The Cure,
or The Cure 2 when that is taken):
- The chapters. One note a chapter, in reading order, numbered:
01 Chapter 1.md. A chapter whose heading has a title of its own after the number is named after it —Chapter 3: The Stormis03 The Storm.md— and its note starts with the heading whole. What comes before the first chapter (other than an AO3 work’s preface) is00 Front matter.md. A chapter’s sections stay headings inside it. index.md. The book’s details as frontmatter, the title, the authors, and the contents as links to the notes. A page with no profile says its title, author, language and the address it was saved from (source), andimported, the day of the conversion. The frontmatter uses the keys a folder’s EPUB export reads (title,author,language,published,series,series_index,description,tags), so the folder exports back to a book.- Pictures beside the page, on the web or written into it are kept as
for a page, in the book folder’s attachments folder (
assets), and the notes point at them there. - Links within the book point at the note they land in, at the nearest heading above where they land; links to the web stay.
One note is the whole book in a single note beside the folder’s
others, its details in its frontmatter and its chapters under their own
## headings, its pictures in the library’s attachments folder.
An AO3 work says all about itself, and the notes keep it:
- The frontmatter of
index.md(and of the one note) hastitle;author, a list;language;published;seriesandseries_indexwhen the work is in one;description, the summary as plain text;tags, the Additional Tags;source, the work’s address;imported; the listsfandom,rating,warnings,category,relationshipsandcharacters; and, when they are given,completedandwords. A work in progress gets new chapters:importedsays whether to download it again. - The body of
index.mdis the summary and the work’s notes, quoted, and the works related to it, then the contents. - A chapter’s own notes are quoted at the top of its note, its end notes at the bottom, and the line “See the end of the chapter for notes” is dropped: the notes are where it points. The work’s end notes close the last chapter.
- A work of one chapter has no chapter heading: its folder holds one note, and One note is the default.
- Left out: the “Preface” and “Afterword” headings the Archive adds, the link to the work and the invitation to comment, the list of tags (it is the frontmatter), and an empty list of works inspired by this one.
A drop or a share of several pages at once converts each as a page, and asks nothing about books: convert a book on its own to cut it into chapters.
Importing a folder
A folder outside the library — a site saved for offline reading, another app’s HTML export, a pile of Markdown — becomes a folder of notes. It starts from a drop on the window (Linux, Windows and macOS; see Dropping files on the window) and from Settings → Maintenance → Import a folder, which picks the folder on every platform (platforms says how on Android and iOS). The offer names the folder and says what it will make — “its Markdown files (12) are copied and its web pages (30) converted into notes” — and nothing is touched until you accept. The folder you chose is left exactly as it was.
What comes in lands in a new folder of the library named after the one
chosen (Site, or Site 2 when that is taken), with the layout it had:
- Markdown files (
.md,.markdown) are copied as they are, but for their links to a page (next but one). - Web pages (
.html,.htm,.xhtml) are each converted into a note, as a page converted on its own is: the article, else the whole body; its frontmatter, its pictures and its links as described there. The note is named after the page’s file, not its title —site/a/b.htmlisa/b.md— so the links between pages map one to one and two pages never take one name. A page whose note would take a name already taken in its folder (b.htmlbesideb.md, or besideb.htm) is numbered,b_2.md; the Markdown file keeps its own. A page that is a book is converted as a page here, not cut into chapters. - Links between the files are rewritten to the notes they became: from a
page or from a Markdown file, a relative link to another page of the
folder —
../x.html,x.html#section,./x.html, written with%20or a backslash, with a query, or to a folder whoseindex.htmlit is — points at the note, relative to the note it is in, and at its heading when it ends in#id(the heading theidis under; a link to anidthe page does not have goes to the note). They are Markdown links whatever the library’s link type, which decides only how a picture is embedded. A link to the web, and a link to a file that is not imported (a PDF, a picture, a stylesheet), stays as it was written. A link inside a Markdown file to another Markdown file is already right and is left alone. - Pictures. The pictures a page shows — those beside it (a browser’s
<Page>_filesfolder), written into it (data:) and on the web — are kept as for a single page, in the library’s attachments folder, each once by what it is, whichever pages show it. Web pictures are downloaded under the web capture’s limits (each under 15 MB, at most 60 for a page) and 500 for the whole import; the ones past them keep their web address. A picture a Markdown file shows is not copied. - Not imported: the browser’s
<Page>_filesfolders (a page’s own files: its frames and its ads are not notes), stylesheets, scripts and every other file, and hidden folders such as.gitor.obsidian.
The import runs in the background with a progress dialog (files done of the total) and Cancel, which leaves the library as it was: everything is written aside and moved in at the end. When it is done, the tree shows the new folder. A page that cannot be read or converted — a text encoding Niman does not read, a file over 32 MiB — is left out, and the message says how many files were; the links to it stay as they were written.
A folder far beyond what a notes app should hold — more than 100 000 notes and pages, more than 1 GiB of them, or more than a million entries to look through — is refused before anything is converted.
Importing a Notion export
Notion’s Export → Markdown & CSV downloads a zip of pages. Settings
→ Maintenance → Import Notion export picks that zip, and so does sharing
it to Niman on Android or dropping it on the window on the desktop. The
pages land in a new folder of the library named after the export: the
page id goes from every name (Roadmap 4a1b….md is Roadmap.md), each
page keeps its children in a folder of its own, and the links between
pages are rewritten to the names they now have — so the result is a
browsable, linked part of the library, not a pile of renamed files.
Images and other attachments come along. What Notion exports for itself
does not: the .csv of a database view, and hidden folders. The zip
itself stays where it was (a share’s copy is deleted with the share). An
export that would expand past what the app can take in — a zip bomb, or a
workspace far larger than a notes app should hold — is refused before it
is unpacked, rather than taking the app down with it.
An Obsidian vault
A vault is opened, not imported: pick the vault folder when opening a
library, and Obsidian’s syntax reads the same way there — [[wikilinks]]
with |aliases, [[folder/note]] paths, ![[image.png]] embeds finding
their attachment by bare name, frontmatter, #tags. The vault’s hidden
folders (.obsidian/, .trash/) stay out of the tree, and everything
else in it that is not Markdown is kept as a file.
Folders, quick note, list notes, voice notes
- Notes live in plain folders inside the library.
- Quick note: one tap target for scratch text. Defaults to
Quick note.mdat the library root;quickNotePathoverrides it, and the note its create button makes goes where new notes go. Text shared into Niman from another app lands at its end (platforms), and the note opens. With Quick note switched off in Features, shared text becomes a new note instead. - List notes: created under
listNoteFolder(defaultLists) and shown as a checklist: tick, nest, drag, edit, delete, add. A list note can be turned into a shopping list (a quantity per item) from its ⋮ menu, and back. See list notes. - Voice notes: made with New voice note in the Files FAB, or
New voice note here in a folder’s right-click menu; a note with
type: audiofrontmatter shows a chat instead of the editor — vocals on the left, written notes on the right. Record (or attach) appends a vocal; clips are plain audio files under the attachments folder (attachmentsFolder, defaultassets), content-addressed like images and linked in the library’s link format (![[…]]for wikilink libraries,for Markdown ones), so they travel with the library. Each vocal carries a title and a description: the> …blockquote lines right above its embed are the title, the ones right under it the description (a quote run sitting between two vocals stays the description of the upper one). A vocal without a title reads asRecording 1,Recording 2, … Each vocal bubble has a round play/pause button, a progress track you can tap or drag to seek, and the elapsed and total time (WAV lengths are read from the file before playing; other formats show theirs once played). Its ⋮ menu — also opened by a long press or a right click — edits the title and the description, copies the description (a transcript or a hand-written comment) to the clipboard, renames the audio file (updating its link) and deletes the vocal. Written notes are sent from the field at the bottom as plain lines (right bubbles); tap one to edit it, long-press or right-click it to delete it. The round button beside the field is the microphone while the field is empty and becomes send as soon as you type; the paperclip inside the field attaches an audio file. The microphone is the messengers’ too: hold it and the recording starts under the finger, slide up past a thumb’s width to lock it so the finger can go free — the bar shows the lock — and let go before that to stop and save, the way a hold is sent; the bar says Slide up to lock while the hold is live, and keeps the lock showing once the finger is off. Let go before the microphone is ready (the first recording can take a moment, and Android may ask for the permission mid-hold) and the recording is thrown away as soon as it starts: nothing was said. A tap keeps the start/stop toggle it always had. While recording, the field shows a red bar with the elapsed time, a pause button (the clock holds and the dot breathes until you resume) and a discard button, and the round button stops and saves; the bar readsSaving…until the new vocal is in the note, and the chat comes to it as it lands — the new bubble is brought into view, so its play button and ⋮ menu are in reach at once (a scroll you make yourself is left alone). Recording writes WAV (PCM 16-bit: playable on Android, Linux and Windows with no extra codec); attaching keeps the file’s own format (.mp3,.m4a,.ogg,.opus,.aac,.flac, …). On Linux recording needspulseaudio-utilsandffmpeginstalled. - Slide notes: a note with
type: slidesfrontmatter is a deck: one slide per---, speaker notes afterNote:, presented full screen (F5) or in the presenter view, and exported as a PDF of 16:9 slides. See slide notes. - Kanban boards: a note with
type: kanbanfrontmatter is a board: a##heading per column, a list item per card. See kanban boards. - Templates: live under
templateFolder(defaultTemplates). See templates.
Transcribing a voice note
Transcription is one of the Features, and needs Audio notes: switched off, there is no Transcribe, and no model is downloaded.
A recording can be written down on the device, with nothing uploaded:
open the vocal’s ⋮ menu (a long press or a right click) and pick
Transcribe. Whisper runs locally, and the text is written into the
vocal’s description — the > lines right after its embed. An empty
description is filled; over one already there, you choose first whether to
replace it or add below, and the snackbar’s Undo puts the
previous description back. Transcription runs in a queue, one recording at
a time, and each bubble shows its progress; closing the note does not stop
it, and the text lands when a view of the note takes it.
The first time, Niman asks which model to use and downloads it once. The models stay in the app’s storage on this device — never in the library, never synced. Settings → Transcription holds the model and the language spoken in your recordings (naming it beats letting whisper detect it, and Same as the app follows the app’s language). Tiny, base, small, medium and large are offered, from fastest-and-least-accurate to most-accurate-and-hungry, and a downloaded model can be deleted there to free its space.
A WAV recording transcribes on every platform. A recording in another format (m4a, mp3, AAC…) transcribes on Android and on a Mac (a clip is converted first) but not on Linux and Windows, where the menu says so under Transcribe; convert it to WAV with a tool of your own first.
Exporting
A note, a folder or the whole library can be written out as plain files: Markdown, or HTML pages that need nothing else to open. See export.