nvALT is a keyboard-first notes app for the Mac. Press a shortcut, type, and the note list narrows as you go. A title that does not match an existing note becomes a new note. Notes stay plain text, the preview is Apex Markdown, and the editor and preview can each take a theme.
It is a fork of Notational Velocity, maintained by me, with earlier work by David Halter. It is free. nvUltra is the app I am building to follow it. nvALT 3 is the version to use on current macOS.
nvALT 3 requires macOS 12 or later. The app runs natively on Apple silicon and on Intel. Check for Updates, in the application menu, uses nvALT’s own update feed.
The interface is localized in English, French, German, Italian, Portuguese, and Chinese.
Download the zip, double-click it, and drag nvALT to Applications.
nvALT keeps its own preferences and note database. Installing it next to an older Notational Velocity, or next to an older nvALT, does not replace that other app’s settings. The first launch of a new major version opens with default settings, so color, sync, and the notes folder need to be chosen again.
Check for Updates after you install. That is the same stream as the download on this page.
⌘+L puts the cursor in the search field. Typing filters the list. ⌘+J and ⌘+K move through the matches. Return opens the selected note for editing. Tab moves between the search field, the tags, and the note body.
A search that matches nothing is a new title. Press Return and the body is empty, ready to type. ⎋ clears the search. ⌘+D deselects the current note and puts the search text back.
⌘+R renames the selected note. ⌘+⌫ deletes the selection. ⇧+⌘+V pastes the clipboard as a new note.
The notes list can sit above the editor or beside it. View, Switch to Horizontal Layout (⌥+⌘+L) flips that, when the editor is not using that shortcut for a list marker. See Lists. ⇧+⌘+C collapses the list. Dragging the divider to the edge of the window hides the search field.
⇧+⌘+K shows or hides the word count.
New libraries are a folder of plain text files. The default extension is md. A library that was already a single database stays a database. An extension you chose yourself stays as it is.
Settings is where you pick the notes folder. If that folder has gone missing, nvALT asks you to pick it again. ⇧+⌘+R shows the selected note in the Finder, when the note is a file on disk.
Rich text libraries can be converted once, from Notes settings, Convert to Markdown. nvALT writes Markdown files into a new folder and switches to that folder. The old folder is left as it was. On first launch, a rich text library also gets a one-time question about converting.
The Note menu lists external editors you have set up. Choosing one writes the note to disk and opens it there. Hold Option while choosing an editor to make that editor the default.
Tags are tokens. Click the tags on a note, or press ⇧+⌘+T. Type a tag and press Space, comma, or semicolon, and it becomes a chip. Existing tags are offered as you type. Return or a click away saves. Escape cancels.
Select more than one note and ⇧+⌘+T opens the same kind of field for the whole selection.
With plain text storage, tags are written to the file as Finder tags. Older OpenMeta tags are copied to Finder tags on launch. Spotlight and tools that read Finder tags can see them. The tag list inside nvALT is still the list nvALT searches.
A normal search matches the title, the body, and the tags. Every word has to match. A quoted phrase is one word, so "shell script" matches that phrase. A colon splits words, so hello:world is a search for hello and a search for world.
⌘+G and ⇧+⌘+G move through matches inside the open note. Search terms are highlighted in the editor. That highlight can be turned off in Settings.
A word that starts with #, with the hash against the word, is a tag search.
#unix keeps a note when either of these is true:
unix. #uni matches unix and unix-admin. It does not match admin-unix.#unix.Case does not matter. A note tagged unix matches even when the body never contains #unix. A note that only writes #unix in the text matches even with no tags. The word unix with no hash, and no unix tag, does not match #unix.
Tag searches combine with everything else. Every part has to match.
#unix shell
#unix #mac
#unix "shell script"# unix is a hash character plus a search for unix, because the hash is not attached to the word. A lone # searches for that character. ##unix is a tag prefix of #unix.
While a # word is in the query, the search field does not complete a note title over what you typed.
The note body is plain text. Markdown completion is on by default (⇧+⌘+M toggles it). With it on, ⌘+B and ⌘+I wrap with the bold and italic markers from Editing settings. Bold is ** or __. Italic is * or _. The defaults are asterisks. The editor colors headings, emphasis, links, lists, quotes, and code. ⌘+T clears formatting. ⌘+Y strikes text through.
Auto-pair, in Settings, inserts the closing bracket, quote, or backtick, and can wrap a selection. The first backtick inserts a pair and leaves the cursor between them. The next backtick types over the closer. A third backtick stays a single character, so three in a row remain a fence, and further backticks extend that run. A backtick typed against a letter is left as one character. Quotes and brackets pair the way they did before.
Invisible characters and unusual spaces are tinted, so a line that looks empty and is not will show itself.
Help, Keyboard Shortcuts opens the in-app list in its own window. The tables below are the same set, grouped by what you are doing.
These list shortcuts need automatic list formatting, the same switch nvALT has used for years.
⌥+⌘+L, while the note body is focused, cycles the current line from plain text to a bullet, to a number, and back. The bullet is the unordered-list marker from Editing settings: -, *, or +. The default is *.
A selection that covers more than one line uses that same cycle for the whole selection. Plain lines gain the bullet after the indent they already have, and blank lines stay blank. When every item is a bullet, the next press numbers them, nested items included. When every item is numbered, the next press removes the markers and leaves the indents. If some lines have a marker and some do not, that press clears the markers instead of numbering. The selection stays on those lines, so the next press continues the cycle.
That cycle runs when automatic list formatting is on. View, Switch to Horizontal Layout uses the same keys, and it runs when the note body is not focused.
Tab indents a list item or a blockquote. Shift-Tab outdents. ⌘+] and ⌘+[ indent and outdent lines, and so do ⌃+⌘+→ and ⌃+⌘+←. The width comes from the tab setting.
Numbered lists renumber as you edit, including nested ones. Return on a list item continues the list. Return on an empty item removes the marker and leaves a blank line.
Return on a blockquote continues the quote. Return on an empty quote line drops the marker. ⇧+⌘+> quotes the line. ⇧+⌘+< removes the quote marker.
Return on the opening line of a code fence writes the closing fence and leaves the cursor between them.
⇧+⌘++ raises the heading level. ⇧+⌘+_ lowers it.
⇧+⌘+L wraps the selection in [[wiki link]] brackets, or inserts an empty pair. Type [[ and note titles complete, when Suggest titles for note-links is on in Editing settings. Return or Tab accepts a title and writes the closing brackets.
A wiki link opens the named note. The preview does not turn those brackets into HTML links. See Apex.
⌥+⌘+K wraps the selection in a Markdown link and leaves the cursor between the parentheses.
[nvALT]()With Markdown completion on, pasting a URL onto a selection fills that link in. Pasting a URL by itself becomes an autolink, <https://example.com>, unless the cursor is already inside a link or a reference definition. Paste Markdown Link (⌥+⌘+V) is the same action from the Edit menu. With Markdown completion off, a pasted URL stays plain text, and that menu item is hidden.
Typing the id in [text][id], or in an image link ![alt][id], offers the definition ids already in the note. A [ at the start of a line starts a definition, and that offers ids used in the note that still have no definition. Typing narrows the list. Return, Tab, or a click accepts one. An existing ] stays put and the cursor moves past it. Ids inside a fenced code block are skipped, and [[wiki links]] still complete note titles.
F6 turns a selection into a reference link and adds the definition at the end of the note. Press F6 on the marker to jump to the definition, or on the definition to jump back.
[the download][1]
[1]: https://brettterpstra.com/projects/nvalt/F7 does the same for footnotes. A selection becomes the footnote body. With nothing selected, the marker lands after the word under the cursor.
Still a notes app.[^1]
[^1]: I mean it.⌘+⏎ opens a URL under the cursor.
⌃+⌘+↑ and ⌃+⌘+↓ move the current paragraph. On a list item, they move that item and anything nested under it.
⌥+⌘+↑ grows the selection by structure: the word, the inside of a pair of markers, the markers, the sentence, the paragraph, the neighboring block, then the whole list, quote, or fence, and finally the note. ⌥+⌘+↓ walks back down.
⌘+← at the start of the body moves to the title. ⌘+→ at the end of the title moves into the body.
| Action | Shortcut |
|---|---|
| Search or create | ⌘+L |
| Clear the search | ⎋ |
| Edit the selected note, or create it | ⏎ |
| Move between title, tags, and body | ⇥ |
| Next note | ⌘+J |
| Previous note | ⌘+K |
| Deselect and restore the search | ⌘+D |
| Rename | ⌘+R |
| Tag | ⇧+⌘+T |
| Delete | ⌘+⌫ |
| Paste as a new note | ⇧+⌘+V |
| Bookmark | ⇧+⌘+D |
| Show in Finder | ⇧+⌘+R |
| Copy the note’s URL | ⌥+⌘+C |
| Import URL | ⇧+⌘+U |
| Export | ⌘+E |
| ⌘+P |
| Action | Shortcut |
|---|---|
| Find | ⌘+F |
| Find and replace | ⌥+⌘+F |
| Find next | ⌘+G |
| Find previous | ⇧+⌘+G |
| Use the selection for Find | ⌥+⌘+E |
| Jump to the selection | ⌥+⌘+J |
| Action | Shortcut |
|---|---|
| Markdown completion | ⇧+⌘+M |
| Bold | ⌘+B |
| Italic | ⌘+I |
| Strikethrough | ⌘+Y |
| Plain text | ⌘+T |
| Wiki link | ⇧+⌘+L |
| Markdown link | ⌥+⌘+K |
| Paste a Markdown link | ⌥+⌘+V |
| Cycle the list marker | ⌥+⌘+L |
| Indent a list item or quote | ⇥ |
| Outdent a list item or quote | ⇧+⇥ |
| Indent lines | ⌘+] or ⌃+⌘+→ |
| Outdent lines | ⌘+[ or ⌃+⌘+← |
| Quote this line | ⇧+⌘+> |
| Remove a quote marker | ⇧+⌘+< |
| Raise the heading level | ⇧+⌘++ |
| Lower the heading level | ⇧+⌘+_ |
| Reference link, or jump to it | F6 |
| Footnote, or jump to it | F7 |
| Move the paragraph up or down | ⌃+⌘+↑ / ⌃+⌘+↓ |
| Expand or shrink the selection | ⌥+⌘+↑ / ⌥+⌘+↓ |
| Action | Shortcut |
|---|---|
| Settings | ⌘+, |
| Word count | ⇧+⌘+K |
| Collapse the notes list | ⇧+⌘+C |
| Horizontal or vertical layout | ⌥+⌘+L |
| Black and white, low contrast, your colors | ⌥+⌘+1 ⌥+⌘+2 ⌥+⌘+3 |
| Note previews in the list | ⌥+⌘+P |
| Preview window | ⌃+⌘+P |
| Preview source | ⌘+U |
| Preview in Marked | ⌃+⌘+M |
| Save preview HTML | ⇧+⌘+S |
⌥+⌘+L is listed twice. In the note body it cycles a list marker. Elsewhere it switches the list layout.
⌃+⌘+P shows the preview. It renders the note with Apex in Unified mode. ⌘+U switches between the rendered page and the HTML source, which is there for copying into a blog or another editor. View includes Enter Full Screen.
Math is typeset with MathJax, and a fenced mermaid block is drawn with Mermaid. Both libraries ship inside the app and load only when that note uses them. A note with neither stays a plain preview. The HTML source view and Save Preview HTML keep the Apex markup. The libraries run in the live preview.
Lock Note to Preview keeps the preview on one note while you edit another. It is in the Preview menu and has no shortcut.
The button at the left of the preview’s icon row follows the cursor. It sits just left of View Source, the </> button, and its tooltip is “Scroll preview with the edit”. It starts off, and that choice is remembered.
While that button is on, the preview stays on the block you are editing and scrolls only when that block leaves the screen. A cursor on a blank line follows the nearest block. Lock Note to Preview does not follow the cursor. The positions used for this stay in the preview. They are not written into the note, and Share Preview does not include them.
⇧+⌘+S saves the preview HTML. Print Preview / PDF prints the rendered page.
The share button at the right of the search field opens the system share menu, downward from the button. A selection in the note body is what gets sent, including edits that are not saved yet. With nothing selected, the whole note goes. A selection in the search field is ignored, and the note title is not included. The tooltip reads “Share Selection” or “Share Note”. The button stays visible and is disabled when there is nothing to send.
Share Preview sits on the preview window, just left of the Marked Share button. It sends the rendered page as rich text, so another notes app can paste it with its formatting. The menu opens upward. Showing the HTML source does not change what is sent: the button still sends the rendered note. It is disabled when the preview has nothing to show. An empty page sends nothing.
Marked Share still copies an unlisted link. The preview toolbar no longer has an Open in Marked button. Send the note to Marked from the system share menu, or use Preview using Marked (⌃+⌘+M). Open Marked Streaming Preview stays in the Preview menu and the status menu.
The preview runs Apex in Unified mode, so one note can use syntax from CommonMark, GitHub Flavored Markdown, MultiMarkdown, Kramdown, and Marked together. The full syntax, with every option, is the Apex wiki. This section is the part you can rely on inside nvALT.
Apex strips a metadata block from the rendered page and can substitute [%key] with a value from that block. YAML front matter, MultiMarkdown metadata, and a Pandoc title block all work.
Standard Markdown is all here: headings, emphasis, lists, links, images, and fenced or indented code. Bare URLs and email addresses become links. Raw HTML is left in the page.
~~struck~~ strikes through. mc^2 is a superscript, and H~2~O puts the 2 in subscript. Tildes on both ends of a word, ~underlined~, underline it. Smart typography turns straight quotes, dashes, and ellipses into typographic ones. :rocket: inserts the emoji.
Inline math is $e = mc^2$. A block is $$ on its own lines. \(...\) and \[...\] work the same way. The preview typesets them with MathJax. Images can take a caption from the title or the alt text.
A fenced block tagged mermaid is drawn in the preview:
```mermaid
flowchart LR
A[Note] --> B[Preview]
```Graphviz and the other diagram types stay as code blocks.
GitHub-style tables work. A colon on the left, the right, or both sides of a dashes cell sets that column’s alignment. A cell can span columns with <<, and rows with ^^. A caption can sit on the line before the table as Table: Caption, or after it as : Caption.
| Task | Owner |
| --- | ---: |
| Write the note | me |Task lists use - [ ] and - [x]. Definition lists use the Kramdown shape, a term and then a line starting with :.
A Bear or Obsidian callout is a quote that starts with a marker:
> [!NOTE]
> The preview renders this as a callout.[!WARNING], [!TIP], and the rest of that set work the same way, including a collapsible callout. Python-Markdown !!! callouts and Quarto ::: callouts are left as ordinary text.
Footnotes use reference syntax, [^id], or an inline form. Critic markup ({++added++}, {--removed--}, {~~old~>new~~}, and comments) is shown in the preview with classes, so a stylesheet can color it.
Inline attribute lists use {#id .class} or {: #id .class}. They attach to the block or span they follow. [text]{#id .class} becomes a span. A fenced div is three or more colons:
::: {.sidebar}
A block with a class.
:::::: >aside uses an <aside> instead of a <div>.
A table of contents marker in the note is filled by Apex. {{TOC}} and <!--TOC--> both work, and {{TOC:2-4}} limits the heading levels. Put those markers in the note. They are not the table of contents for this page.
Headings get ids. Abbreviations, indices, and citations are available. Citations need a bibliography named in the note’s metadata. The citations and indices pages describe the syntax.
A few Apex switches are off when nvALT renders a note:
[[wiki links]] stay as brackets in the HTML. In the editor they are still links to other notes. See Links.mermaid fence is drawn. See Diagrams.File includes and a few other processor flags are documented on the Apex wiki. The preview is rendering the note you are editing.
Settings, Fonts & Colors has two menus, one for the editor and one for the preview, plus Import and Open Themes Folder.
Default is the nvALT color scheme from that same pane, and the preview from template.html and custom.css. Those two files live in Application Support and are the right place for a preview that needs its own HTML or JavaScript. A named theme replaces them while it is selected.
Everything you import lives in one folder:
~/Library/Application Support/nvALT/ThemesThe first time that folder is used, a sample pair named Paper is copied in. It is not selected for you. Drop files in the folder or use Import. .theme, .plist, and .json are editor themes. .css files are preview themes.
The note font and the notes-list font are set in this pane. The defaults are SF Pro at 16 pt for the body and 14 pt for the list. A font you already chose is left alone. Keep Note Body Width Readable limits the line length. The margins use the window color.
With no editor theme, the window chrome follows system light and dark mode.
An editor theme is a MultiMarkdown Composer theme. Composer writes JSON. nvALT also reads an XML or binary plist, and a .json file that uses the same keys. Export a theme from Composer, or copy one out of its themes folder, and import it.
Colors are #RGB, #RRGGBB, or #RRGGBBAA. They are painted on screen and are not written into the note. Switching back to Default, or to another theme, does not bake the last palette into the file.
backgroundColor and foregroundColor color the window, including the title bar, the divider, and the scrollbars. The scrollbar knob uses the window foreground when it has to stay visible against the track.
textView paints the note: background, text, caret, and selection. The notes list uses tableView, tableViewHighlighted, and tableViewInactive when those exist, and falls back to the window colors when they do not.
Syntax is a dictionary per element. heading, strong, emphasis, codeBlock, codeSpan, blockquote, markup, linkParens, and the rest of the Composer set all apply. A heading level can sit on top of the base heading style. Each style can set foregroundColor, backgroundColor, markupForegroundColor, bold, italic, strikethrough, and mono.
fontScale is part of the Composer format. nvALT ignores it. The type size stays where Fonts & Colors put it.
Svelte is the theme in the screenshot. The whole file is Svelte.theme. This link installs it:
Edit the .theme file in any text editor. It is JSON. Save, and nvALT reads it from the themes folder.
A preview theme is CSS. The note is rendered inside <div id="wrapper">, the same hook Marked uses, so a Marked stylesheet can be dropped in. Style #wrapper, or style h1, p, pre, and the rest of the elements inside it. Rules on body still paint the page around the note.
body {
margin: 0;
background: #f4f1ea;
}
#wrapper {
max-width: 42em;
margin: 0 auto;
padding: 2.4em 2.2em 4em;
font: 18px/1.55 Palatino, Georgia, serif;
}nvalt:// and nv:// both accept a theme. The host is add-theme or import-theme. Percent-encode a url value. A local file can use path, and a ~ in that path is expanded.
nvalt://add-theme?url=https%3A%2F%2Fraw.githubusercontent.com%2Fttscoff%2Fnv%2Fmaster%2Fexamples%2FSvelte.theme
nv://add-theme?path=/Users/me/Desktop/GitHub.cssThe file is copied into the themes folder and selected. url can be a file, http, or https address. If a server sends the theme as plain text, nvALT still imports it.
View, Color Schemes still switches the built-in black and white scheme, the low-contrast scheme, and your own scheme, with ⌥+⌘+1, ⌥+⌘+2, and ⌥+⌘+3. Those apply when you are on Default.
Note, Import URL (⇧+⌘+U) asks for an address and creates a note. If the clipboard is a single web address, that address is already filled in. A host with no scheme is fine. nvALT adds https://.
Dragging a URL onto the notes list still works.
Convert imported URLs to Markdown, in Settings, brings the page in as Markdown. Process with Readability extracts the article first. Hold Option when you choose Import URL, or Option-drag a URL onto the list, and Readability runs for that import even when the preference is off.
The new note is selected as soon as it arrives. The search field is set to the note’s title, so a leftover search does not hide it.
The converter is built into the app. It uses the same HTML2Text and Readability setup as Marked.
The extensions clip a whole page, the current selection, or one or more blocks. A block picker highlights as you hover. ⌘+ or Shift-click adds another block.
The Safari extension ships inside nvALT. Turn it on in Safari Settings. The Chrome, Brave, Firefox, and Zen extensions are installed separately. Source and install notes are on GitHub.
nvalt://markdownify and nv://markdownify do the same conversion for a script or a browser extension. Pass the page as url, or the HTML itself as html. When you pass html, url is only the source link. title and readability (1 or 0) are optional. This URL always writes Markdown, even when Convert imported URLs to Markdown is off.
nvalt://markdownify?url=https://brettterpstra.com
nvalt://markdownify?html=...&url=https://brettterpstra.com&readability=1Simplenote sync is in Notes settings, on the Synchronization tab. Sign-in emails you a code. Paste the code and press Return. An expired code is reported so you can email yourself a new one.
If Simplenote sync is on and notes are stored in Dropbox or SimpleText, nvALT warns you.
Finder tags, described under Tags, are the on-disk tag store. They are independent of Simplenote.
| URL | What it does |
|---|---|
nvalt://find/Title/ |
Opens the named note. Copy URL (⌥+⌘+C) puts a full link on the clipboard, including an id so the note can still be found after a rename. nv:// is accepted anywhere nvalt:// is. |
nvalt://markdownify |
Imports a page or a piece of HTML as a Markdown note. See The markdownify URL. |
nvalt://add-theme |
Copies a theme into the themes folder and selects it. See Install a theme from a link. |
⌘+, opens Settings. The sidebar lists four panes.
[[wiki links]], right-to-left text, and the URL import switches. Convert imported URLs to Markdown and Process with Readability live here. See Editing and Importing pages.Note previews in the list are ⌥+⌘+P.
The menu bar icon is a separate status menu, with search, preview, and quit. Show Main Window is ⇧+⌘+N.
Questions, bugs, and feature requests go in the GitHub issues. Please look through the open tickets before opening a new one. A ticket is the thread I can keep up to date.
A few older walkthroughs are still worth reading for the basic search-and-type habit. Michael Schechter’s nvALT 101, and this introduction in French.
#### CHANGED
</> icon, and the sync toggle sits to its left#### CHANGED
#### FIXED
#### NEW
#### NEW
#### FIXED
#### NEW
#### FIXED
#### FIXED
#### FIXED
#### FIXED
#### FIXED
#### NEW
** or __), italic (* or _), and unordered lists (-, *, or +)[text][id] from definitions already in the note, and a new [id]: line offers ids that are still unused#### NEW
[text][id] from definitions already in the note, and a new [id]: line offers ids that are still unused#### NEW
$...$, $$...$$, \(...\), and \[...\]#### FIXED
#### NEW
#### NEW
#### NEW
#### CHANGED
nvalt:// and nv://) turns a page URL or raw HTML into a Markdown note, with an optional title and Readability override. It converts even when Convert imported URLs to Markdown is off.#### CHANGED
#### CHANGED
#### CHANGED
#### FIXED
#### FIXED
#### FIXED
#### NEW
#### CHANGED
#### CHANGED
#### CHANGED
#### CHANGED
#### CHANGED
#### CHANGED
#### CHANGED
nvALT 3.0 is the current line. The posts after that announcement cover Markdown editing, themes, and tagging and web clipping.
A fork of Notational Velocity with Apex preview and advanced Markdown editing capabilities. Other good stuff.
Published 06/08/13.
Updated 11/08/26. Changelog
Check for Updates, in the application menu, follows this fork only.
Source is on GitHub. Branches are where I try things. master can be ahead of the last release, and it can be broken.
Speaking of nvALT…
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on GitHub, Mastodon, and elsewhere.
Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader, or following it on Bluesky or Mastodon at @brettterpstra.com@web.brid.gy.