org-roam.nvim

Port of Org-roam to neovim using nvim-orgmode.

Requires neovim 0.9.2+.

Videos

Installation

This plugin depends on nvim-orgmode/orgmode 0.3.4 or newer.

It is recommended to install and maintain the latest version of orgmode, or lock into the commit that this plugin needs, which is illustrated below.

Org Roam Version	Orgmode Version
0.1.0	0.3.4

lazy.nvim (recommended)

Code Example

{
  "chipsenkbeil/org-roam.nvim",
  tag = "0.1.0",
  dependencies = {
    {
      "nvim-orgmode/orgmode",
      tag = "0.3.4",
    },
  },
  config = function()
    require("org-roam").setup({
      directory = "~/orgfiles",
    })
  end
}

packer.nvim

Code Example

use {
  "chipsenkbeil/org-roam.nvim",
  tag = "0.1.0",
  requires = {
    {
      "nvim-orgmode/orgmode",
      tag = "0.3.4",
    },
  },
  config = function()
    require("org-roam").setup({
      directory = "~/orgfiles",
    })
  end
}

Bindings

Name	Keybinding	Description
add_alias	<Leader>naa	Adds an alias to the node under cursor.
add_origin	<Leader>noa	Adds an origin to the node under cursor.
capture	<Leader>nc	Opens org-roam capture window.
complete_at_point	<Leader>n.	Completes the node under cursor.
find_node	<Leader>nf	Finds node and moves to it, creating it if it does not exist.
goto_next_node	<Leader>nn	Goes to the next node in sequence (via origin) for the node under cursor.
goto_prev_node	<Leader>np	Goes to the prev node in sequence (via origin) for the node under cursor.
insert_node	<Leader>ni	Inserts node at cursor position, creating it if it does not exist.
insert_node_immediate	<Leader>nm	Same as insert_node, but skips opening capture buffer.
quickfix_backlinks	<Leader>nq	Opens the quickfix menu for backlinks to the current node under cursor.
remove_alias	<Leader>nar	Removes an alias from the node under cursor.
remove_origin	<Leader>nor	Removes the origin from the node under cursor.
toggle_roam_buffer	<Leader>nl	Toggles the org-roam node-view buffer for the node under cursor.
toggle_roam_buffer_fixed	<Leader>nb	Toggles a fixed org-roam node-view buffer for a selected node.

Dailies Extension

Name	Keybinding	Description
capture_date	<Leader>ndD	Capture a specific date’s note.
capture_today	<Leader>ndN	Capture today’s note.
capture_tomorrow	<Leader>ndT	Capture tomorrow’s note.
capture_yesterday	<Leader>ndY	Capture yesterday’s note.
find_directory	<Leader>nd.	Navigate to dailies note directory.
goto_date	<Leader>ndd	Navigate to specific date’s note.
goto_next_date	<Leader>ndf	Navigate to the next note in date sequence.
goto_prev_date	<Leader>ndb	Navigate to the previous note in date sequence.
goto_today	<Leader>ndn	Navigate to today’s note.
goto_tomorrow	<Leader>ndt	Navigate to tomorrow’s note.
goto_yesterday	<Leader>ndy	Navigate to yesterday’s note.

Documentation

See DOCS.org for detailed guidance on the plugin.

The documentation is also generated in vimdoc help format, which can be accessed via :h org-roam.txt.

Roadmap

A collection of features to implement in no particular order.

• [-] Implement org-roam buffer
  • [X] Implement org-roam-buffer-toggle (tracks current node at point)
  • [X] Implement org-roam-buffer-display-dedicated (tracks specific node)
  • [X] Implement Backlinks widget for buffer
    • View (preview of) nodes that link to this node
  • [ ] Implement Reference Links widget for buffer
    • Nodes that reference this node (see Refs)
  • [ ] Implement Unlinked references widget for buffer
    • View nodes that contain text that match the nodes title/alias but are not linked
  • [X] Implement Origin widget for buffer (custom, not in Org Roam!)
    • Displays the origin of the node as defined in ROAM_ORIGIN
• [ ] Support citations
  • [ ] As of orgmode 9.5, org-cite is built-in and has the form [cite:@key]
  • [ ] Alongside org-cite, there is also support for org-ref (v2 & v3), which uses cite:key as its format
• [X] Support completion
  • [X] Completing within Link Brackets
  • [X] Completing anywhere
• [X] Support templating
  • [X] Implement org-roam-node-insert
  • [X] Implement org-roam-node-find
  • [X] Implement org-roam-capture
  • [X] Implement org-roam-node-insert-immediate
• [X] Support origin (custom, not in Org Roam!)
  • [X] ROAM_ORIGIN available within node properties, containing org id
  • [X] Ability to query database for nodes with origin matching an id
  • [X] Keybinding to jump forward and backward across origins
• [X] Miscellaneous Roam functions
  • [X] Implement org-roam-alias-add
  • [X] Implement org-roam-alias-remove
  • [X] Implement org-roam-origin-add (custom, not in Org Roam!)
  • [X] Implement org-roam-origin-remove (custom, not in Org Roam!)
• [-] Implement extensions
  • [X] org-roam-dailies
  • [ ] org-roam-export
  • [ ] org-roam-graph
  • [ ] org-roam-protocol

Developer & Contributor Instructions

Running tests

A makefile is provided to support running tests. It will download plenary.nvim and nvim-orgmode into the vendor directory.

make test