Niman

Links

Forms (target, heading, alias combine freely):

  • [[note]] — link to a note
  • [[note|alias]] — displayed as alias
  • [[note#heading]] — jumps to the heading
  • [[note#heading|alias]]
  • [[#heading]] / [[|alias]] — the current note

Click (or Ctrl+click in the source editor) to navigate. What the editor highlights, the preview links, and the indexer records are the same set: links inside code fences, math blocks, inline code, and frontmatter are never links, everywhere.

While a link is typed, a small panel lists what can go there, in both editors, under the caret. Only typing opens it: a caret moved into a link already written — an arrow key, a click — opens nothing, and the keys stay the note’s. The panel lists:

  • after [[ — the library’s notes, the name shown and the folder dimmed (what tells two same-named notes apart). A note is matched by its name and by its frontmatter aliases, prefix matches first; a row found through an alias says which one. Choosing a note whose name another note shares writes as much of its folder as it takes to name that one ([[Work/Meeting]]), so the link opens the note that was picked. A note whose name holds #, |, [ or ] is not listed: a [[…]] target has no escape for them, and the row would write a link that reads back as another note — link to one of those with a Markdown link instead ([C# tips](C%23%20tips.md));
  • after a # — the headings of the note just named, filtered the same way. [[# — no target — lists the headings of the note being edited;
  • after a # on a PDF or an EPUB — the place form to type, page= or chapter=. Once the form’s key is written, what follows the = is the number you type: the panel is not offered again there, so ⏎ or Tab cannot write the form over it.

The panel does not open inside code or maths: a [[ in a fenced or indented code block, in display maths or in an inline code or maths span is the code’s own text, and completing it there would write a note name and a ]] into it. In a very long note whose colours are still being read, the panel waits for them — the next keystroke in the link opens it.

↑/↓ move, ⏎ or Tab complete the link, Esc closes the panel and leaves the text as it was. Typed into a link already closed, the choice replaces the whole name (or heading) up to its #, | or ]]; what follows is kept. The panel writes nothing but the link that was chosen: no note is created from it, and a name that matches nothing is left as typed (see Dead links below for where a new note comes from). The rows come from the index the app already keeps; nothing is scanned to fill the panel.

Standard [text](href) links, and reference links — [text][label] with a [label]: href line anywhere in the note. href may be a relative path to a note or any other file of the library (Books/Dune.epub), a #anchor, or an external URL. The path may be percent-encoded, as Obsidian writes it: [x](My%20Note.md) is My Note.md. A path with no extension is not followed. ![alt](src) images are not links, and neither is a footnote reference ([^1]); a link written inside a footnote’s own text is.

A path is read the way Markdown reads it, against the library:

  • /docs/a.md is docs/a.md from the library root, and no other note whose path merely ends in it;
  • ../Notes/a.md walks from the folder of the note it is written in (in Deep/Sub/b.md it is Deep/Notes/a.md, in Sub/b.md it is Notes/a.md), and names exactly that path. One that climbs out of the library names nothing: the link is dead, it never falls back to a note of the same name elsewhere;
  • a plain path (a.md, sub/a.md) is tried beside the note first: in Sub/b.md, [x](a.md) is Sub/a.md when there is one. When there is not, it is found as a wikilink is: by its name, and the note’s folder qualifies it (sub/a.md matches x/sub/a.md), the picker offering the candidates when more than one fits.

A wikilink is a name, not a path, so a plain [[a]] is never read beside the note; [[/docs/a]] and [[../Notes/a]] follow the same rules as the Markdown forms. A note outside the library is not in the index and so is not a link target. \ in a path is /.

Moving a note, or a folder of them, moves what its relative links name: the backlinks and dead links follow the new folder at once, without opening or editing the note. A link that names another note by its name only ([[a]]) does not care where either note is. A link written with a path to a note that moved, from a note that did not, is read again when that note is next indexed.

A link can point at a place inside a PDF or an EPUB book; following it opens the file in the note pane there, instead of where you left it. Wikilinks and Markdown links alike:

  • [[Dune.pdf#page=34]], [p. 34](Dune.pdf#page=34) — page 34 of a PDF, the form Obsidian and PDF readers use. Other parameters, such as an Obsidian embed’s height=400, are passed over.
  • [[Dune.epub#chapter=OEBPS/ch5.xhtml&line=12]] — line 12 of a chapter of a book, the chapter named by its file inside the EPUB (its name alone is enough, chapter=ch5.xhtml). Niman’s own form: there is no common one for books, and Obsidian opens the book, ignoring it.
  • &chars=3-40 after either names a passage: its characters in the PDF page’s text, or in the text of the book’s paragraph on that line. An annotation’s link carries it, for the file to mark just the passage; following it goes to the page or the paragraph.

You rarely write one by hand: the link button on the row under a PDF or a book copies a link to the place you are reading — the page, or the chapter’s line at the top of the view — as the library writes links ([[Books/Dune.pdf#page=34|Dune, p. 34]], or [Dune, p. 34](Books/Dune.pdf#page=34) with Markdown links), ready to paste into a note. The button is disabled for a file opened from outside a library.

A link to a file already open moves it to the place; the same link followed again goes back there. A place the file no longer has (a page past its end, a chapter it lost) opens it where you left it.

A link whose target note does not exist is a dead link, and a dead link is where a note comes from. In the editor, Ctrl+click (Cmd+click on macOS), the same gesture that follows a link, is its own confirmation: the note the link names is created on the spot and opened, and the writer is left in it.

Anywhere else — a tap in the preview, or on a touch screen, where there is no Ctrl — following a dead link offers to create it: a dialog shows the proposed path with Create and Cancel. Create makes an empty note there (no frontmatter) and opens it in the editor; Cancel changes nothing — no file, no error, no second prompt.

Where the new note lands is the library setting missingNoteLocation (Settings → Editor):

  • currentFolder (default) — the folder of the note where the link was clicked: [[Foo]] in Notes/Current.md creates Notes/Foo.md
  • libraryRoot — the library root: [[Foo]] creates Foo.md

A target that names a folder ([[Sub/Foo]]) keeps that folder; Niman does not create intermediate folders, so a missing folder shows an error. Targets with an extension ([[photo.png]]) are attachments, not notes: they are never created. External URLs keep their behavior.

Notes opened without a library (editor-only mode) keep the old “link not found” outcome.

The editor’s link button inserts a wikilink by default; set the library’s linkType to markdown to insert […](…) instead.

Edit this page on GitHub