Skip to content

chipsenkbeil/org-roam.nvim

Repository files navigation

org-roam.nvim logo

org-roam.nvim

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

Requires neovim 0.9.4+.

Videos

Installation

This plugin depends on nvim-orgmode/orgmode 0.3.7 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 VersionOrgmode VersionNeovim Version
0.1.10.3.70.9.4+
0.1.00.3.40.9.2+

lazy.nvim (recommended)

Code Example
{
  "chipsenkbeil/org-roam.nvim",
  tag = "0.1.1",
  dependencies = {
    {
      "nvim-orgmode/orgmode",
      tag = "0.3.7",
    },
  },
  config = function()
    require("org-roam").setup({
      directory = "~/org_roam_files",
      -- optional
      org_files = {
        "~/another_org_dir",
        "~/some/folder/*.org",
        "~/a/single/org_file.org",
      }
    })
  end
}

packer.nvim

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

Bindings

NameKeybindingDescription
add_alias<Leader>naaAdds an alias to the node under cursor.
add_origin<Leader>noaAdds an origin to the node under cursor.
capture<Leader>ncOpens org-roam capture window.
complete_at_point<Leader>n.Completes the node under cursor.
find_node<Leader>nfFinds node and moves to it, creating it if it does not exist.
goto_next_node<Leader>nnGoes to the next node in sequence (via origin) for the node under cursor.
goto_prev_node<Leader>npGoes to the prev node in sequence (via origin) for the node under cursor.
insert_node<Leader>niInserts node at cursor position, creating it if it does not exist.
insert_node_immediate<Leader>nmSame as insert_node, but skips opening capture buffer.
quickfix_backlinks<Leader>nqOpens the quickfix menu for backlinks to the current node under cursor.
remove_alias<Leader>narRemoves an alias from the node under cursor.
remove_origin<Leader>norRemoves the origin from the node under cursor.
toggle_roam_buffer<Leader>nlToggles the org-roam node-view buffer for the node under cursor.
toggle_roam_buffer_fixed<Leader>nbToggles a fixed org-roam node-view buffer for a selected node.

Dailies Extension

NameKeybindingDescription
capture_date<Leader>ndDCapture a specific date’s note.
capture_today<Leader>ndNCapture today’s note.
capture_tomorrow<Leader>ndTCapture tomorrow’s note.
capture_yesterday<Leader>ndYCapture yesterday’s note.
find_directory<Leader>nd.Navigate to dailies note directory.
goto_date<Leader>nddNavigate to specific date’s note.
goto_next_date<Leader>ndfNavigate to the next note in date sequence.
goto_prev_date<Leader>ndbNavigate to the previous note in date sequence.
goto_today<Leader>ndnNavigate to today’s note.
goto_tomorrow<Leader>ndtNavigate to tomorrow’s note.
goto_yesterday<Leader>ndyNavigate 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] 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

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