Links, tags & search

Links, wikilinks & backlinks

• [[Note Title]] links to another note by its exact title (case insensitive). Type [[ to trigger autocomplete of existing titles. A wikilink to a title that doesn’t exist yet still renders, just styled as “broken” until a matching note is created; opening it creates the note.
• Pointing at a folder: when two notes share a title, put the folder in front, [[people/John]]. The folder can be the last part of a longer path (people also finds work/people/John); start with / to count from the vault root ([[/people/John]]). Folder and note names match the way they read in the sidebar, ignoring case. Opening a link like this to a note that doesn’t exist yet creates it in that folder. Without a folder, [[John]] picks the John nearest the vault root.
• Different link text: [[people/John|Johnny]] links to John but reads “Johnny”.
• Opening a link in Preview Since 0.20.0: click it. A note opens in its tab, and a URL in your browser. Cmd/Ctrl+click opens a note in the background, so you stay on this one. Rest the mouse on a link to see where it goes. See Clicking in Preview.
• Editing a link in Preview: right-click it and choose Edit link… to open a small editor. Since 0.20.0 For a wikilink, pick the note (notes that share a title show their folder, and picking one fills in folder/Title; or type a name that doesn’t exist yet to link to a new note) and set the text it shows; for a regular link, change its text and URL. Open follows the link, Remove link keeps the text and drops the link, Save (or Enter) applies, Esc cancels. To type in the link’s text instead, choose Edit text on its card, move the cursor into it with the arrow keys, or click just beside it. Since 0.20.0
• From the keyboard Since 0.20.0: with the cursor in a link, ModEnter opens it, and Mod. opens its card (see the card). Remove link keeps the text: removing [[#Intro]] leaves Intro, not a tag; so does Remove link in the link editor. A wikilink inside code doesn’t open or create a note.
• Pasting a bare URL over an empty cursor wraps it as <url>; pasting over a text selection turns the selection into [selected text](url).
• Backlinks: the right sidebar’s “Linked from N notes” section lists every note that links to the one you’re viewing (via [[wikilink]] or a regular link to its title). Click one to open it at the line holding its link, shaded until you click, type or move the cursor in the note; a database opens as a table instead. The backlinks pill above the note shows the count; click it for a card listing them (see Note pills). A wikilink in an attribute counts too, such as author: "[[Ursula K. Le Guin]]" or an item in a list. That note is listed with the attribute it links through, for example “The Dispossessed via author”, and opens at the top. Since 0.12.0
• Linking from outside the vault: a permalink links to a note from a pull request, an issue or a chat, and keeps working when the note is renamed or moved. Since 0.16.0

Link to a heading Since 0.14.0

Add # and a heading’s text after the note’s title to link to that heading: [[Roadmap#Next steps]], or [[Roadmap#Next steps|what's next]] with different link text. [[#Next steps]] links to a heading in the note you’re writing.

• In Preview the link reads Roadmap › Next steps, or › Next steps for a heading in the same note.
• Type [[Roadmap# to list that note’s headings, or [[# for the current note’s.
• Opening the link opens the note at the heading. If the note has no such heading any more, it opens at the top and a notice says Heading not found.
• The heading’s text matches ignoring case. When two headings have the same text, the link goes to the first. Only headings at the top level of the note count, not one inside a quote or a list.
• A heading link counts as a backlink to its note.
• Markdown links work the same way: [next steps](roadmap.md#next-steps) and [next steps](#next-steps) jump to the heading, by its text or by its anchor (lowercase, with dashes for spaces).

To copy a link to a heading, hover over it (or put the cursor on its line) and click the link icon at the end of the line, which copies [[Roadmap#Next steps]]. You can also right-click a heading in the outline, or run Copy link to heading from the command palette with the cursor on a heading. There’s no copy for the note’s title, in an encrypted note or in a read-only view.

Tags Since 0.12.0

Any # immediately followed by a letter (and not inside code, a link or a URL) is a tag: #project, #ideas, etc. A note’s frontmatter tags: list counts too (tags: [project, ideas], or one - item per line; a leading # is optional). Mahfouz picks tags up automatically.

Suggested tags Since 0.14.0

Type # in a note and Mahfouz lists the vault’s tags, most used first, with how many notes carry each. Keep typing to narrow the list: tags that start with what you typed come first, then tags that contain it. The tags you picked last appear under Recent at the top.

• Use the arrow keys to pick a tag, then press Enter. Without the arrow keys, Enter starts a new line, so a tag you finish typing yourself stays as you typed it.
• At the start of a line the list waits for the first letter (#i), since # followed by a space starts a heading.
• The list doesn’t open inside code, links or wikilinks.

The same list, with a search field, opens from Add tag in a note’s tags attribute. Recent tags are kept on this computer only, per vault, and never in the vault. The Tasks tab filters by tags with + Add filter → Tags instead. Since 0.15.0

Every tag can be clicked. Clicking one opens the Search tab with tag:name in its field, listing the notes that have that tag in every vault: Since 0.13.0

• In Preview, click the tag. In Source, Cmd/Ctrl+click it (a plain click places the cursor so you can edit it). In Preview, to edit it, choose Edit text on its card (right-click it), or click just beside it. Since 0.20.0
• A #tag on a task title in the Tasks view, a chip in a note’s tags attribute, and a tag in the right sidebar’s Tags section work the same way.

With a tag: in the search, Narrow by under the search field lists the other tags those notes carry. Click one to add it as another tag:: only notes with all the tags stay. To remove a tag, use the × on its chip in the summary line, or delete it from the field. Since 0.13.0

While you type tag: and part of a name, Matching tags lists the tags whose names contain it, so tag:pro offers #project and #improv. Click one to finish the word. person: does the same with people’s handles and names. Since 0.13.0

With the search field empty, the Search tab lists every tag with its note count, and Untagged, which searches is:untagged for notes with no tags. Since 0.13.0

Rename a tag

Rename tag… renames a tag in every note of every vault that has it. Open it from the tag’s menu:

• In the Search tab, right-click a tag in the list it shows while the field is empty, or a tag under Narrow by. Since 0.13.0
• In the editor, right-click a tag (in Preview or Source) and choose Rename tag… on its card. Since 0.20.0 With the cursor on a tag and nothing selected, ShiftF10, Mod. Since 0.20.0 or the Menu key opens the same card. Its first item, Search #tag, searches for the tag, as ModEnter on it does. Since 0.20.0

The dialog counts the notes it will change in each vault. Type the new name after the #. A tag starts with a letter, followed by letters, digits, - or _. Capitals are lowercased as you type, and a leading # is dropped. If the new name is a tag that already exists, the dialog says so and the button becomes Merge: the two tags become one, and a tags: list that had both keeps it once.

Each vault gets one commit, Rename tag #old to #new. What’s rewritten:

• #old in note bodies, in any case (#Old becomes #new), including inside pending suggestions.
• Items of a frontmatter tags: list. The list keeps its style: one - item per line, or [a, b], with any quotes or leading #.

What stays as it is:

• #old inside code, a URL, a link’s destination or a wikilink, and in comment entries.
• Longer tags that start the same way, such as #old-ideas or #older.
• Vaults with a stopped git operation (a merge or rebase, for example), and vaults that are git-crypt locked or need to be reconnected. These aren’t searched.
• Notes whose edits are waiting for your choice, and encrypted notes.

The dialog lists what will be skipped before you rename. Disk-only notes are renamed but stay out of the commit.

When it’s done, one notification reports every vault. If a vault fails, its changes are undone, the others keep theirs, and the notification offers Try again.

Merge a tag into another

Since 0.14.0

Merge into…, under Rename tag… in the same menus, folds a tag into one that already exists. In the editor it reads Merge #name into…. The dialog lists every other tag in your vaults with its note count; type to filter it, pick the tag to keep, and choose Merge. It’s the same change as renaming onto that tag: one commit per vault, the same text rewritten and the same notes skipped.

Search

ModShiftF, the command palette’s Search all notes row Since 0.14.0, or the scope button in the note’s Find bar opens the Search tab in the main pane. There’s one Search tab: opening it again brings it to the front with its query, results and place kept. The tab is titled with what you searched for. Since 0.13.0

It searches the titles and text of your notes in all open vaults as you type. With text selected in the note, or a query in its Find bar, ModShiftF starts the search with it. On the desktop, Edit → Find in All Notes does the same. Since 0.13.0

A word matches anywhere inside a word, so udget finds “budget”, and كتاب finds “والكتاب” and “بالكتاب”. Words of three letters or more are looked up in the search index; shorter words still match, more slowly. A note has to match every word you type. Notes whose title matches come first.

You can narrow a search with:

Match case (Aa), Match whole word (ab) and Use regular expression (.*) in the search field work as they do in the note’s Find bar, and AltC, AltW and AltR switch them. With one of them on, a long search can stop with “Search too slow; narrow it”. Since 0.13.0

The sort sits beside the search field, on the same row: Relevance, Edited or Title (on a narrow pane, on its own line under the field). Under the field, a summary line shows the tag:, person:, in: and is:untagged filters you’ve used as chips (click × on one to remove it from the search). The count in the field reads how many matches in how many notes. Since 0.13.0

The results are grouped by note: its title, where it sits (its folders, and its vault when you have more than one open), then a row for each matching line, with its line number and your matches highlighted. A note lists up to 20 lines, then says how many more it has. Since 0.13.0

The note you open highlights the words and phrases you searched for, never the operators, while the Search tab stays open, and shades the line you opened until you click, type or move the cursor in the note.

With the search field empty, the tab lists your recent searches, every tag with its note count (see Tags) and a few search tips. Recent searches are kept on this device only.

An encrypted note is found by its title only: its text isn’t searched.

Replace across notes Since 0.13.0

Click the chevron at the left of the search field to show the Replace field. Each match in the results then reads old → new: the old text struck through, the new text underlined.

• Each note has a checkbox. Untick a note to leave it out.
• A match on the line a note’s title comes from has its own changes the title box, unticked at first. A note whose title changes may have its file renamed in a following commit.
• A note in Suggesting mode is marked as suggestions: it gets each replacement as a tracked substitution instead. Matches a suggestion can’t change, such as someone else’s suggestion or a link’s address, are left as they are.
• In every note, matches in suggestion and comment markup (a suggestion’s author, a comment’s entries) are left as they are, so a replace never changes who wrote them.
• Encrypted notes, notes whose edits are waiting for your choice and vaults that are git-crypt locked are skipped. A line under the summary says what’s left out.

Replace (Enter in the Replace field) changes the matches on the highlighted line. Replace all (ModEnter) names what it changes, such as “7 in 2 notes”, and asks once before writing. When the search stopped early, because it hit its limit or ran too long, Replace all is off until you narrow it. After you change the Replace text, both buttons are off for a moment, until the preview shows the new text.

Each vault gets one commit, Replace "old" with "new" in N notes. A note that changed since the preview (its text, or a switch between Editing and Suggesting), or has Windows line endings, is skipped, and the others go ahead. One notification reports what changed, what was skipped and how many matches were left as they are. If a vault fails, its changes are undone.

To jump to a note by its title or text Since 0.14.0, run a command or open a setting, use the command palette (ModK) instead.