Getting Started

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

Requires neovim 0.9.4+.

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 Version	Orgmode Version	Neovim Version
0.1.1	0.3.7	0.9.4+
0.1.0	0.3.4	0.9.2+

lazy.nvim

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

packer.nvim

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
}

Configuration

org_files

To include existing org files in the knowledge graph of org roam, additional files can be registered. Supported syntax is like org_agenda_files in orgmode. If the entry does not end on .org a directory is assumed and searched recursively for org files.

require("org-roam").setup({
  org_files = {
    "~/more_org_files",
    "~/additional/org_files/*.org",
  },
})

To actually connect the content of these files with org-roams knowledge graph, you can use the “store link” feature of orgmode (<Leader>ols), which adds an ID to an existing headline. This headline is then treated as a roam node by org-roam.

If you want a whole file to be treated as a node by org-roam, you need to add a global property section and a title at the top of the org file.

:PROPERTIES:
:ID: 8b2c3d3e-9800-4186-80e5-d07ce7bc5327
:END:
#+TITLE: My node

Tip: Because “store link” in orgmode currently does not support whole files, the quick workaround is to apply <Leader>ols on a headline and move the :PROPERTIES: section with the generated ID to the top of the file.

bindings

Configuration settings used to specify keybindings.

prefix

Sets an overall prefix, to define common leading keystrokes for other bindings. Defaults to <Leader>n.

require("org-roam").setup({
  bindings = {
    prefix = "<LocalLeader>n",
  },
})

It can be used in other bindings with <prefix>:

require("org-roam").setup({
  bindings = {
    prefix = "<LocalLeader>n",
    -- ...
    add_alias = "<prefix>A", -- add alias is now bound to <LocalLeader>nA
  },
})

All default keybindings use it, so if you just want to change <Leader>n to something else, instead of redefining them all manually, just set bindings.prefix to your preference. See also *Modifying bindings.

add alias

Adds an alias to the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>naa.

require("org-roam").setup({
  bindings = {
    add_alias = "<LocalLeader>naa",
  },
})

add origin

Adds an origin to the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>noa.

require("org-roam").setup({
  bindings = {
    add_origin = "<LocalLeader>noa",
  },
})

capture

Opens a roam capture window.

Takes a string representing the keybinding. Defaults to <Leader>nc.

require("org-roam").setup({
  bindings = {
    capture = "<LocalLeader>nc",
  },
})

complete at point

Completes the node under cursor by searching for a node with matching title or alias. If exactly one match is found, the text under cursor is replaced with the link; otherwise, a selection dialog pops up to pick the node.

Takes a string representing the keybinding. Defaults to <Leader>n..

require("org-roam").setup({
  bindings = {
    complete_at_point = "<LocalLeader>n.",
  },
})

find node

Finds a node by title or alias and opens it in the current window.

If the node does not exist, opens a capture buffer for the new node using the title.

Takes a string representing the keybinding. Defaults to <Leader>nf.

require("org-roam").setup({
  bindings = {
    find_node = "<LocalLeader>nf",
  },
})

goto next node

Goes to the next node sequentially based on origin of the node under cursor.

If more than one node has the node under cursor as its origin, a selection dialog is displayed to choose the node.

Takes a string representing the keybinding. Defaults to <Leader>nn.

require("org-roam").setup({
  bindings = {
    goto_next_node = "<LocalLeader>nn",
  },
})

goto prev node

Goes to the previous node sequentially based on origin of the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>np.

require("org-roam").setup({
  bindings = {
    goto_prev_node = "<LocalLeader>np",
  },
})

insert node

Inserts a link at cursor position to a node by title or alias.

If the node does not exist, opens a capture buffer for the new node using the title.

Takes a string representing the keybinding. Defaults to <Leader>ni.

require("org-roam").setup({
  bindings = {
    insert_node = "<LocalLeader>ni",
  },
})

insert node immediate

Inserts a link at cursor position to a node by title or alias. Unlike insert_node, this does not open a capture buffer if a new node is created.

Takes a string representing the keybinding. Defaults to <Leader>nm.

require("org-roam").setup({
  bindings = {
    insert_node_immediate = "<LocalLeader>nm",
  },
})

quickfix backlinks

Opens the quickfix list, populating it with backlinks for the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>nq.

require("org-roam").setup({
  bindings = {
    quickfix_backlinks = "<LocalLeader>nq",
  },
})

remove alias

Removes an alias from the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>nar.

require("org-roam").setup({
  bindings = {
    remove_alias = "<LocalLeader>nar",
  },
})

remove origin

Removes the origin from the node under cursor.

Takes a string representing the keybinding. Defaults to <Leader>nor.

require("org-roam").setup({
  bindings = {
    remove_origin = "<LocalLeader>nor",
  },
})

toggle roam buffer

Opens the roam buffer for the node under cursor, updating the buffer when the cursor moves to a different node. See the user interface Org Roam Buffer section for details.

Takes a string representing the keybinding. Defaults to <Leader>nl.

require("org-roam").setup({
  bindings = {
    toggle_roam_buffer = "<LocalLeader>nl",
  },
})

toggle roam buffer fixed

Opens the roam buffer for a specific node, and will not change as the cursor moves across nodes. See the user interface Org Roam Buffer section for details.

Takes a string representing the keybinding. Defaults to <Leader>nb.

require("org-roam").setup({
  bindings = {
    toggle_roam_buffer_fixed = "<LocalLeader>nb",
  },
})

database

Configuration settings tied to the roam database.

path

Sets the path where the roam database will be stored & loaded when persisting to disk.

Takes a string representing the path. Defaults to For example, ~/.local/share/nvim/org-roam.nvim/db.

require("org-roam").setup({
  database = {
    path = "~/some/path/to/db",
  },
})

persist

If true, the database will be written to disk to save on future loading times; otherwise, whenever neovim boots the entire database will need to be rebuilt.

Takes a boolean. Defaults to true.

require("org-roam").setup({
  database = {
    persist = false,
  },
})

update on save

If true, updates database whenever a write occurs. If you have large files, it is recommended to disable this option and manually update using the vim command RoamUpdate.

Takes a boolean. Defaults to true.

require("org-roam").setup({
  database = {
    update_on_save = false,
  },
})

extensions

Configuration settings tied to roam extensions.

dailies

Configuration settings tied to the roam dailies extension.

bindings

Configuration settings used to specify dailies keybindings.

capture date

Captures a specific date’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndD.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        capture_date = "<LocalLeader>ndD",
      },
    },
  },
})

capture today

Captures today’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndN.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        capture_today = "<LocalLeader>ndN",
      },
    },
  },
})

capture tomorrow

Captures tomorrow’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndT.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        capture_tomorrow = "<LocalLeader>ndT",
      },
    },
  },
})

capture yesterday

Captures yesterday’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndY.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        capture_yesterday = "<LocalLeader>ndY",
      },
    },
  },
})

find directory

Navigate to dailies note directory.

Takes a string representing the keybinding. Defaults to <Leader>nd..

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        find_directory = "<LocalLeader>nd.",
      },
    },
  },
})

goto date

Navigate to specific date’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndd.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_date = "<LocalLeader>ndd",
      },
    },
  },
})

goto next date

Navigate to the next note in date sequence. This will skip ahead to the next available note, or do nothing if we are at most recent.

Takes a string representing the keybinding. Defaults to <Leader>ndf.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_next_date = "<LocalLeader>ndf",
      },
    },
  },
})

goto prev date

Navigate to the previous note in date sequence. This will skip back to the previous available note, or do nothing if we are at earliest.

Takes a string representing the keybinding. Defaults to <Leader>ndb.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_prev_date = "<LocalLeader>ndb",
      },
    },
  },
})

goto today

Navigate to today’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndn.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_today = "<LocalLeader>ndn",
      },
    },
  },
})

goto tomorrow

Navigate to tomorrow’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndt.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_tomorrow = "<LocalLeader>ndt",
      },
    },
  },
})

goto yesterday

Navigate to yesterday’s note.

Takes a string representing the keybinding. Defaults to <Leader>ndy.

require("org-roam").setup({
  extensions = {
    dailies = {
      bindings = {
        goto_yesterday = "<LocalLeader>ndy",
      },
    },
  },
})

templates

A map of templates associated with roam. These have the exact same format as nvim-orgmode’s templates, but include additional variables and are only displayed and used during roam’s capture dialog.

Note that the target must be provided and must contain a date in the form of YYYY-MM-DD. See templates for more details.

Takes a table<string, table>. Defaults to the following:

require("org-roam").setup({
  extensions = {
    dailies = {
      templates = {
        d = {
          description = "default",
          template = "%?",
          target = "%<%Y-%m-%d>.org",
        },
      },
    },
  },
})

ui

Configuration settings used to configure dailies user interface.

calendar

Configuration settings tied to the calendar ui used by dailies.

hl date exists

Highlight group to apply to a date that already has a note.

Takes a string representing the highlight group. Defaults to WarningMsg.

require("org-roam").setup({
  extensions = {
    dailies = {
      ui = {
        calendar = {
          hl_date_exists = "WarningMsg",
        },
      },
    },
  },
})

immediate

Configuration settings tied to immediate mode.

target

Target where the immediate-mode node should be written.

Takes a string. Defaults to %<%Y%m%d%H%M%S>-%[slug].org.

require("org-roam").setup({
  immediate = {
    target = "%[slug].org",
  },
})

template

Template to use for the immediate-mode node’s content.

Takes a string. Defaults to ==.

require("org-roam").setup({
  immediate = {
    template = "The date is %<%Y%m%d>!",
  },
})

templates

A map of templates associated with roam. These have the exact same format as nvim-orgmode’s templates, but include additional variables and are only displayed and used during roam’s capture dialog.

Takes a table<string, table>. Defaults to the following:

require("org-roam").setup({
  templates = {
    d = {
      description = "default",
      template = "%?",
      target = "%<%Y%m%d%H%M%S>-%[slug].org",
    },
  },
})

Variables:

%r: Prints the roam directory.
%R: Like %r, but inserts the full path.

Target-only Variables:

%[sep]: Prints the path separator for the current operating system.
%[slug]: Prints a slug representing the node’s title.
%[title]: Prints the node’s title.

ui

Configuration settings tied to the user interface.

node view

Bindings tied specifically to the roam buffer.

focus on toggle

If true, switches focus to the node buffer when opened.

Takes a boolean. Defaults to true.

require("org-roam").setup({
  ui = {
    node_buffer = {
      focus_on_toggle = false,
    },
  },
})

highlight previews

If true, previews will be highlighted as org syntax when expanded.

NOTE: This can cause flickering on initial expansion, but preview highlights are then cached for future renderings. If flickering is undesired, disable highlight previews.

Takes a boolean. Defaults to true.

require("org-roam").setup({
  ui = {
    node_buffer = {
      highlight_previews = false,
    },
  },
})

open

Configuration to open the node view window.

Takes a string or a function that returns a window handle. Defaults to botright vsplit | vertical resize 50.

require("org-roam").setup({
  ui = {
    node_buffer = {
      open = function()
        return vim.api.nvim_open_win(0, false, {
          relative = "editor",
          row = 0,
          col = 0,
          width = 50,
          height = 20,
        })
      end,
    },
  },
})

show keybindings

If true, will include a section covering available keybindings.

Takes a boolean. Defaults to true.

require("org-roam").setup({
  ui = {
    node_buffer = {
      show_keybindings = false,
    },
  },
})

unique

If true, shows a single link (backlink/citation/unlinked reference) per node instead of all links.

Takes a boolean. Defaults to false.

require("org-roam").setup({
  ui = {
    node_buffer = {
      unique = true,
    },
  },
})

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.

All these bindings use by default the *prefix alias and can be changed all at once by modifying bindings.prefix.

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.

All these bindings use by default the *prefix alias and can be changed all at once by modifying bindings.prefix.

Modifying bindings

Bindings can be changed during configuration by overwriting them within the bindings table:

require("org-roam").setup({
  -- ...
  bindings = {
    capture = "<LocalLeader>nc" -- remaps from <Leader>nc to <LocalLeader>nc
  },
})

We use a common *prefix to define the leading keystrokes in every mapping, which are by default <Leader>n. If you only want to adjust these, you can do so by setting bindings.prefix:

require("org-roam").setup({
  -- ...
  bindings = {
    prefix = "<LocalLeader>n", -- replaces <Leader>n in every binding with <LocalLeader>n
  },
})

The *prefix can also be reused in self-defined bindings:

require("org-roam").setup({
  -- ...
  bindings = {
    toggle_roam_buffer = "<prefix>t.",       -- replaces <Leader>nl with <Leader>nt.
    toggle_roam_buffer_fixed = "<prefix>tf", -- replaces <Leader>nb with <Leader>ntf
  },
})

To disable all bindings (including those of extensions), set the bindings field to false:

require("org-roam").setup({
  -- ...
  bindings = false,
})

To disable only the bindings of an extension, set its respective bindings field to false:

require("org-roam").setup({
  -- ...
  extensions = {
    dailies = {
      bindings = false,
    }
  },
})

Coming from Emacs

Want to have bindings similar to Emacs’s Org Roam? Here is a recommended setup you can use to leverage C-c

require("org-roam").setup({
  bindings = {
    add_alias                = "<C-c>naa",
    add_origin               = "<C-c>noa",
    capture                  = "<C-c>nc",
    complete_at_point        = "<M-/>",
    find_node                = "<C-c>nf",
    goto_next_node           = "<C-c>nn",
    goto_prev_node           = "<C-c>np",
    insert_node              = "<C-c>ni",
    insert_node_immediate    = "<C-c>nm",
    quickfix_backlinks       = "<C-c>nq",
    remove_alias             = "<C-c>nar",
    remove_origin            = "<C-c>nor",
    toggle_roam_buffer       = "<C-c>nl",
    toggle_roam_buffer_fixed = "<C-c>nb",
  },
})

Keep in mind that nvim-orgmode maps C-c to closing a capture window, so you’ll want to rebind it:

-- Override `org_capture_finalize` mapping to make org-roam mappings work in capture window
require("orgmode").setup({
  mappings = {
    capture = {
      -- Behave like Emacs' orgmode capture
      org_capture_finalize = "<C-c><C-c>",
    }
  }
})

Commands

RoamAddAlias

:RoamAddAlias [<ARGS>]

Description:

Adds an alias to the node under the cursor.

If arguments are supplied, they are used as the alias; otherwise, a prompt is provided to specify the alias.

RoamAddOrigin

:RoamAddOrigin [<ARGS>]

Description:

Adds/replaces the origin to the node under the cursor. Opens a selection dialog to pick the node to act as the origin.

If arguments are supplied, they are used as the initial input to the selection dialog.

RoamRemoveAlias

:RoamRemoveAlias [<ARGS>]

Description:

Removes an alias for the node under the cursor. Opens a selection dialog to pick the alias to remove.

If arguments are supplied, they are used as the initial input to the selection dialog.

RoamRemoveOrigin

:RoamRemoveOrigin [<ARGS>]

Description:

Removes the origin for the node under the cursor.

RoamReset

:RoamReset [sync]

Description:

Resets the roam database, wiping and rebuilding it.

If sync argument is provided, will perform the reset synchronously.

RoamSave

:RoamSave[!] [sync]

Description:

Save the roam database to disk. If no changes to the database have occurred since last save, nothing happens.

If ! is provided, will force saving.

If sync argument is provided, will perform the save synchronously.

RoamUpdate

:RoamUpdate[!] [sync]

Description:

Updates the roam database, checking every existing file for changes.

If ! is provided, will perform a complete recheck of the database for changes found on disk including new and deleted files.

If sync argument is provided, will perform the update synchronously.

User Interface

Org Roam Buffer

When within the org-roam buffer, you can navigate around like normal with a couple of specific bindings available:

Press <Enter> on a link to navigate to it in another window.
Press <Tab> to expand or collapse a preview of the content of a backlink, reference link, or unlinked reference.
Press <STab> to expand or collapse all previews.
Press <C-r> to refresh the buffer. This can be handy if some information has changed in the database.

Select Buffer

When within the select buffer, you can filter the list by typing.

Press <Enter> to confirm the selection
Press <S-Enter> to confirm the typed title if no selection is available (e.g. when using Find Node)
Press <C-n> or <Down> to select the next item in the list
Press <C-n> or <Up> to select the next item in the list

Disable nvim-cmp completion in select buffer

If you use buffer completions with [nvim-cmp](https://github.com/hrsh7th/nvim-cmp), you might want to disable them in the select buffer. This can be done by implementing the enabled function in nvim-cmp’s options.

The simplest implementation would be to look for the nofile buffer type

require('nvim-cmp').setup({
  enabled = function()
    local buftype = vim.api.nvim_get_option_value("buftype", { buf = 0 })
    if buftype == "nofile" then
      return false
    end
    -- ... handling other conditions
  end
})

If for some reason you don’t want to disable completion for all nofile buffers, you can also specifically identify the select buffer by it’s name org-roam-select.

require('nvim-cmp').setup({
  enabled = function()
    local bufname = vim.api.nvim_buf_get_name(0)
    if bufname:match("org%-roam%-select$") ~= nil then
      return false
    end
    -- ...
  end
})

API

Add Alias

roam.api.add_alias({opts})

Description:

Adds an alias to the node under cursor.

Parameters:

{opts} optional table.
- alias: optional, if provided, added to the node under cursor, otherwise prompts for an alias to add to the node under cursor.

Returns:

A promise of a boolean, which is true if the alias is added, otherwise false.

Example:

local roam = require("org-roam")
roam.api.add_alias({ alias = "My Alias" }):next(function(success)
  if success then
    print("Added alias")
  end
end)

Add Origin

roam.api.add_origin({opts})

Description:

Adds an origin to the node under cursor. Will replace the existing origin.

If no `origin` is specified, a prompt is provided.

Parameters:

{opts} optional table.
- origin: optional, if provided, added to the node under cursor, otherwise prompts for an origin to add to the node under cursor.

Returns:

A promise of a boolean, which is true if the origin added, otherwise false.

Example:

local roam = require("org-roam")
roam.api.add_origin({ origin = "1234" }):next(function(success)
  if success then
    print("Added origin")
  end
end)

Capture Node

roam.api.capture_node({opts})

Description:

Creates a node if it does not exist, prompting for a template to use, and restores the current window configuration upon completion.

If templates is provided, will be used instead of roam.config.templates.

Parameters:

{opts} optional table.
- immediate: optional, if true, skips displaying the capture buffer and instead populates a file using the immediate configuration. If title is also provided, it is used as the title of the created node.
- origin: optional, id of node acting as origin of this node.
- templates: optional, dictionary of key -> opts where key is a string of exactly one character and opts is the orgmode template. Note that the target MUST be specified for each template!
- title: optional, seeds the capture dialog with the title string.

Returns:

A promise of either the id of the captured node, or nil if capture canceled.

Example:

local roam = require("org-roam")
roam.api.capture_node({
  templates = {
    c = {
      description = "custom",
      template = "%?",
      target = "custom-%<%Y%m%d>.org",
    },
  },
}):next(function(id)
  if id then
    print("Captured node: " .. id)
  else
    print("Capture canceled")
  end
end)

Complete Node

roam.api.complete_node({opts})

Description:

Opens a dialog to select a node based on the expression under the cursor and replace the expression with a link to the selected node. If there is only one choice, this will automatically inject the link without bringing up the selection dialog.

This implements the functionality of both org-roam-complete-link-at-point and org-roam-complete-everywhere.

Parameters:

{opts} optional table.
- win: optional, id of window where the node link will be completed (default = 0).

Returns:

A promise of a boolean, which is true if the node was completed, otherwise false.

Example:

local roam = require("org-roam")
roam.api.complete_node({ win = 123 }):next(function(success)
  if success then
    print("Completed node")
  end
end)

Find Node

roam.api.find_node({opts})

Description:

Creates a node if it does not exist, and then visits the node in the current window.

If templates is provided, will be used instead of roam.config.templates when capturing a new node for visiting.

Parameters:

{opts} optional table.
- origin: optional, id of node acting as origin of this node (creation-only).
- templates: optional, dictionary of key -> opts where key is a string of exactly one character and opts is the orgmode template. Note that the target MUST be specified for each template!
- title: optional, seeds the select dialog with the title string.

Returns:

A promise of either the id of the found node, or nil if canceled.

Example:

local roam = require("org-roam")
roam.api.find_node({ title = "Some Node" }):next(function(id)
  if id then
    print("Found " .. id)
  end
end)

Goto Next Node

roam.api.goto_next_node({opts})

Description:

Goes to the next node in sequence for the node under cursor.

Leverages a lookup of nodes whose origin match the node under cursor.

Parameters:

{opts} optional table.
- win: optional, id of window where buffer will be loaded (default = 0).

Returns:

A promise of the id of the next node, otherwise nil.

Example:

local roam = require("org-roam")
roam.api.goto_next_node({ win = 123 }):next(function(id)
  if id then
    print("Navigated to next node " .. id)
  end
end)

Goto Prev Node

roam.api.goto_prev_node({opts})

Description:

Goes to the previous node in sequence for the node under cursor.

Leverages a lookup of the node using the origin of the node under cursor.

Parameters:

{opts} optional table.
- win: optional, id of window where buffer will be loaded (default = 0).

Returns:

A promise of the id of the previous node, otherwise nil.

Example:

local roam = require("org-roam")
roam.api.goto_prev_node({ win = 123 }):next(function(id)
  if id then
    print("Navigated to previous node " .. id)
  end
end)

Insert Node

roam.api.insert_node({opts})

Description:

Creates a node if it does not exist, and inserts a link to the node at the current cursor location.

If immediate is true, no template will be used to create a node and instead the node will be created with the minimum information and the link injected without navigating to another buffer.

If templates is provided, will be used instead of roam.config.templates when capturing a new node for insertion.

If ranges is provided, will replace the given ranges within the buffer versus inserting at point, where everything uses 1-based indexing and inclusive.

Parameters:

{opts} optional table.
- immediate: optional, if true, skips displaying the capture buffer and instead populates a file using the immediate configuration. If title is also provided, it is used as the title of the created node.
- origin: optional, id of node acting as origin of this node (creation-only).
- templates: optional, dictionary of key -> opts where key is a string of exactly one character and opts is the orgmode template. Note that the target MUST be specified for each template!
- title: optional, seeds the select dialog with the title string.
- ranges: optional, list of ranges to replace. Each range is comprised of the following fields:
  - start_row: integer (one-indexed, inclusive)
  - start_col: integer (one-indexed, inclusive)
  - end_row: integer (one-indexed, inclusive)
  - end_col: integer (one-indexed, inclusive)

Returns:

A promise of the id of the inserted node, or nil if canceled.

Example:

local roam = require("org-roam")
roam.api.insert_node({
  title = "Some Node",
  ranges = { { start_row = 1, end_row = 3, start_col = 5, end_col = 12 } },
}):next(function(id)
  if id then
    print("Inserted node " .. id)
  end
end)

Open Quickfix List

roam.ui.open_quickfix_list({opts})

Description:

Creates and opens a new quickfix list, populated with various links tied to a roam node.

Parameters:

{opts} optional table.
- id: optional, string id of the node whose information will populate the list. If not provided, will open a selection dialog to pick a node.
- backlinks: optional, if true, show’s the selected node’s backlinks.
- links: optional, if true, show’s the selected node’s links.
- show_preview: optional, if true, loads a preview of content for each list item.

Returns:

A promise of a boolean, which is true if the quickfix list is opened for a node, otherwise false (e.g. when no node under cursor).

Example:

local roam = require("org-roam")
roam.ui.open_quickfix_list({ id = "1234", backlinks = true }):next(function(success)
  if success then
    print("Opened quickfix list")
  end
end)

Select Node

roam.ui.select_node({opts})

Description:

Builds a selection dialog populated by nodes, displaying their titles and aliases as choices in the selection. Returns a builder interface.

Parameters:

{opts} optional table.
- allow_select_missing: optional, if true, the user can press <Enter> when no choices are available to select the input instead. Additionally, a user can press <S-Enter> at any time in the selection dialog to select the input, regardless of choices shown.
- auto_select: optional, if true and init_input is not empty, will automatically pick the choice if there is exactly one match.
- exclude: optional, list of ids of nodes to exclude from choices.
- include: optional, list of ids of nodes to include in the choices. If not provided, all nodes will immediately be available.
- init_input: optional, string representing initial input to provide to the selection dialog, as if the user typed it.

Returns:

A builder interface for the selection dialog, which contains a handful of methods that can be used to register callbacks and open the dialog.

{on_choice} takes a single function, which will be passed the selection as an argument. The selection is a table containing an id and label representing the id of the selected node and the title or alias of the choice that was picked. This function is only called when a regular selection is made, not when input selected. Returns the builder.
{on_choice_missing} takes a single function, which will be passed the text of the input as an argument. This function is only called when allow_select_missing is true and the input is selected instead of a valid choice. Returns the builder.
{on_cancel} takes a single function, which is invoked when the selection dialog is closed without making any choice. Returns the builder.
{open} will open the selection dialog, and returns the window handle.

Example:

local roam = require("org-roam")
local win = roam.ui.select_node({ init_input = "trees" })
    :on_choice(function(selection)
        print("picked " .. selection.id)
    end)
    :on_choice_missing(function(text)
        print("picked " .. text)
    end)
    :on_cancel(function()
        print("canceled")
    end)
    :open()

Toggle Node Buffer

roam.ui.toggle_node_buffer({opts})

Description:

Toggles an org-roam buffer, either for a cursor or for a fixed id.

If fixed is true or an string, will load a fixed buffer, otherwise the buffer will change based on the node under cursor.

If focus is true, will switch the current window to the node buffer’s window.

Parameters:

{opts} optional table.
- fixed: optional, indicates that the node buffer should not update when the node changes under the cursor. Takes the id of a node or a boolean value, which if true will leverage the select dialog to pick a node.
- focus: optional, if true, switches the current window to the newly-created window that contains the node buffer.

Returns:

A promise of the handle of the created window, or nil if window closed.

Example:

local roam = require("org-roam")
roam.ui.open_node_buffer({ fixed = "1234", focus = true }):next(function(win)
  if win then
    print("Opened node buffer in window " .. win)
  end
end)

Remove Alias

roam.api.remove_alias({opts})

Description:

Removes an alias from the node under cursor.

Parameters:

{opts} optional table.
- alias: optional, if provided, removes from node under cursor, otherwise prompts for an alias to remove from the node under cursor.
- all: optional, if true, will remove all aliases instead of just one. Overrides removing alias from node under cursor.

Returns:

A promise of a boolean, which is true if the alias was removed, otherwise false.

Example:

local roam = require("org-roam")
roam.api.remove_alias({ all = true }):next(function(success)
  if success then
    print("Removed alias")
  end
end)

Remove Origin

roam.api.remove_origin()

Description:

Removes the origin from the node under cursor.

Returns:

A promise of a boolean, which is true if the origin was removed, otherwise false.

Example:

local roam = require("org-roam")
roam.api.remove_origin():next(function(success)
  if success then
    print("Removed origin")
  end
end)

Database

Files

roam.database:files({opts})

Description:

Loads org files (or retrieves from cache) asynchronously.

Parameters:

{opts} optional table.
- force: optional, if true, will reload each file regardless of whether they have changed on disk. If false, only reloads pre-existing files if they have changed.
- skip: optional, if true, will avoid loading entirely and just return the files as they are (no updates).

Returns:

A promise of OrgFiles, a specialized data structure from nvim-orgmode.

Example:

local roam = require("org-roam")
roam.database:files():next(function(files)
  for _, path in ipairs(files.paths) do
    print("File " .. path)
  end
end)

Files Path

roam.database:files_path()

Description:

Returns the path to the files directory.

Example:

local roam = require("org-roam")
roam.database:files_path()

Files Sync

roam.database:files_sync({opts})

Description:

Loads org files (or retrieves from cache) synchronously. Will throw an error if timeout is exceeded.

Parameters:

{opts} optional table.
- force: optional, if true, will reload each file regardless of whether they have changed on disk. If false, only reloads pre-existing files if they have changed.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.
- skip: optional, if true, will avoid loading entirely and just return the files as they are (no updates).

Returns:

An instance of OrgFiles, a specialized data structure from nvim-orgmode.

Example:

local roam = require("org-roam")
local files = roam.database:files_sync()
for _, path in ipairs(files.paths) do
  print("File " .. path)
end

Find Nodes by Alias

roam.database:find_nodes_by_alias({alias})

Description:

Retrieves nodes with the specified alias from the database.

Operation is performed asynchronously, returning a promise of a list of nodes that have the alias.

Parameters:

{alias} string representing the node’s alias.

Returns:

A promise of a list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
roam.database:find_nodes_by_alias("Some Alias"):next(function(nodes)
  for _, node in ipairs(nodes) do
    print("Got node " .. node.id)
  end
end)

Find Nodes by Alias Sync

roam.database:find_nodes_by_alias_sync({alias}, {opts})

Description:

Retrieves nodes with the specified alias from the database. Operation is performed synchronously, returning a list of nodes. Will throw an error if timeout is exceeded.

Parameters:

{alias} string representing the node’s alias.
{opts} optional table.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

A list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
local nodes = roam.database:find_nodes_by_alias_sync("Some Alias")
for _, node in ipairs(nodes) do
  print("Got node " .. node.id)
end

Find Nodes by File

roam.database:find_nodes_by_file({file})

Description:

Retrieves nodes with the specified file from the database.

Operation is performed asynchronously, returning a promise of a list of nodes that have the file.

Parameters:

{file} string representing the node’s file path.

Returns:

A promise of a list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
roam.database:find_nodes_by_file("path/to/file.org"):next(function(nodes)
  for _, node in ipairs(nodes) do
    print("Got node " .. node.id)
  end
end)

Find Nodes by File Sync

roam.database:find_nodes_by_file_sync({file}, {opts})

Description:

Retrieves nodes with the specified file from the database. Operation is performed synchronously, returning a list of nodes. Will throw an error if timeout is exceeded.

Parameters:

{file} string representing the node’s file path.
{opts} optional table.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

A list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
local nodes = roam.database:find_nodes_by_file_sync("path/to/file.org")
for _, node in ipairs(nodes) do
  print("Got node " .. node.id)
end

Find Nodes by Tag

roam.database:find_nodes_by_tag({tag})

Description:

Retrieves nodes with the specified tag from the database.

Operation is performed asynchronously, returning a promise of a list of nodes that have the tag.

Parameters:

{tag} string representing the tag.

Returns:

A promise of a list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
roam.database:find_nodes_by_tag("example"):next(function(nodes)
  for _, node in ipairs(nodes) do
    print("Got node " .. node.id)
  end
end)

Find Nodes by Tag Sync

roam.database:find_nodes_by_tag_sync({tag}, {opts})

Description:

Retrieves nodes with the specified tag from the database. Operation is performed synchronously, returning a list of nodes. Will throw an error if timeout is exceeded.

Parameters:

{tag} string representing the tag.
{opts} optional table.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

A list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
local nodes = roam.database:find_nodes_by_tag_sync("example")
for _, node in ipairs(nodes) do
  print("Got node " .. node.id)
end

Find Nodes by Title

roam.database:find_nodes_by_title({title})

Description:

Retrieves nodes with the specified title from the database.

Operation is performed asynchronously, returning a promise of a list of nodes that have the title.

Parameters:

{title} string representing the node’s title.

Returns:

A promise of a list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
roam.database:find_nodes_by_title("Some Title"):next(function(nodes)
  for _, node in ipairs(nodes) do
    print("Got node " .. node.id)
  end
end)

Find Nodes by Title Sync

roam.database:find_nodes_by_title_sync({title}, {opts})

Description:

Retrieves nodes with the specified title from the database. Operation is performed synchronously, returning a list of nodes. Will throw an error if timeout is exceeded.

Parameters:

{title} string representing the node’s title.
{opts} optional table.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

A list of org-roam.core.file.Node.

Example:

local roam = require("org-roam")
local nodes = roam.database:find_nodes_by_title_sync("example")
for _, node in ipairs(nodes) do
  print("Got node " .. node.id)
end

Get

roam.database:get({id})

Description:

Retrieves a node from the database by its id. Operation is performed asynchronously, returning a promise of the node or nil if none exists.

Parameters:

{id} string representing the node’s id.

Returns:

A promise of org-roam.core.file.Node | nil.

Example:

local roam = require("org-roam")
roam.database:get("1234"):next(function(node)
  if node then
    print("Got node " .. node.title)
  end
end)

Get Sync

roam.database:get_sync({id}, {opts})

Description:

Retrieves a node from the database by its id. Operation is performed synchronously, returning the node or nil if none exists.

Parameters:

{id} string representing the node’s id.
{opts} optional table.
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

org-roam.core.file.Node or nil.

Example:

local roam = require("org-roam")
local node = roam.database:get_sync("1234")
if node then
  print("Got node " .. node.title)
end

Get File Backlinks

roam.database:get_file_backlinks({file}, {opts})

Description:

Retrieves ids of nodes linking to a file. Operation is performed asynchronously, returning a promise of a table of id -> distance away from the file.

Parameters:

{file} string representing a file path.
{opts} optional table.
- max_depth: optional, integer representing maximum depth to traverse from the nodes of the file (default 1).

Returns:

A promise of table<string, integer> where the keys are the ids of nodes and the values are the distance from the file in terms of backlinks.

For immediate backlinks, the values will be 1.

Example:

local roam = require("org-roam")
roam.database:get_file_backlinks("path/to/file.org"):next(function(backlinks)
  for id, distance in pairs(backlinks) do
    print("Got node " .. id .. " with distance " .. distance)
  end
end)

Get File Backlinks Sync

roam.database:get_file_backlinks_sync({id}, {opts})

Description:

Retrieves ids of nodes linking to a file. Operation is performed synchronously, returning a table of id -> distance away from the file. Will throw an error if timeout is exceeded.

Parameters:

{file} string representing a file path.
{opts} optional table.
- max_depth: optional, integer representing maximum depth to traverse from the nodes of the file (default 1).
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

table<string, integer> where the keys are the ids of nodes and the values are the distance from the file in terms of backlinks.

For immediate backlinks, the values will be 1.

Example:

local roam = require("org-roam")
local backlinks = roam.database:get_file_backlinks_sync("path/to/file.org")
for id, distance in pairs(backlinks) do
  print("Got node " .. id .. " with distance " .. distance)
end

Get File Links

roam.database:get_file_links({file}, {opts})

Description:

Retrieves ids of nodes linked from a file. Operation is performed asynchronously, returning a promise of a table of id -> distance away from the file.

Parameters:

{file} string representing a file path.
{opts} optional table.
- max_depth: optional, integer representing maximum depth to traverse from the nodes of the file (default 1).

Returns:

A promise of table<string, integer> where the keys are the ids of nodes and the values are the distance from the file in terms of links.

For immediate links, the values will be 1.

Example:

local roam = require("org-roam")
roam.database:get_file_links("path/to/file.org"):next(function(links)
  for id, distance in pairs(links) do
    print("Got node " .. id .. " with distance " .. distance)
  end
end)

Get File Links Sync

roam.database:get_file_links_sync({id}, {opts})

Description:

Retrieves ids of nodes linked from a file. Operation is performed synchronously, returning a table of id -> distance away from the file. Will throw an error if timeout is exceeded.

Parameters:

{file} string representing a file path.
{opts} optional table.
- max_depth: optional, integer representing maximum depth to traverse from the nodes of the file (default 1).
- timeout: optional, integer representing maximum time (in milliseconds) to wait for the operation to complete. Throws error on timeout.

Returns:

table<string, integer> where the keys are the ids of nodes and the values are the distance from the file in terms of links.

For immediate links, the values will be 1.

Example:

local roam = require("org-roam")
local links = roam.database:get_file_links_sync("path/to/file.org")
for id, distance in pairs(links) do
  print("Got node " .. id .. " with distance " .. distance)
end

Load

roam.database:load({opts})

Description:

Loads the database from disk and re-parses files. Returns a promise that receives a database reference and collection of files.

Parameters:

{opts} optional table.
- force: optional, boolean or “scan”. if true, will reload each file and node regardless of whether they have changed on disk. If “scan”, will check for new or removed files. If false, only reloads pre-existing files and nodes if they have changed.

Returns:

A promise of {database:org-roam.core.Database, files:OrgFiles}.

Example:

local roam = require("org-roam")
roam.database:load({ force = true }):next(function(results)
  ---@type OrgFiles
  local files = results.files
end)

Load File

roam.database:load_file({opts})

Description:

Loads the database from disk and re-parses files. Returns a promise that receives an org file and list of roam nodes.

Parameters:

{opts} required table.
- path: required, string representing the path to the file.
- force: optional, if true, will reload each file and node regardless of whether they have changed on disk. If false, only reloads pre-existing files and nodes if they have changed.

Returns:

A promise of {file:OrgFile, nodes:org-roam.core.file.Node[]}.

Example:

local roam = require("org-roam")
roam.database:load_file({ path = "path/to/file.org" }):next(function(results)
  ---@type OrgFile
  local file = results.file

  ---@type org-roam.core.file.Node[]
  local node = results.nodes
end)

Path

roam.database:path()

Description:

Returns the path to the database on disk.

Returns:

A string representing the path.

Example:

local roam = require("org-roam")
roam.database:path()

Save

roam.database:save({opts})

Description:

Saves the database to disk. Returns a promise of nil.

Parameters:

{opts} optional table.
- force: optional, if true, will reload each file and node regardless of whether they have changed on disk. If false, only reloads pre-existing files and nodes if they have changed.

Returns:

A promise of boolean representing whether or not the database saved.

This will be false if there have been no changes to the database since last save and force was not set to true.

Example:

local roam = require("org-roam")
roam.database:save():next(function()
  print("Done!")
end)

Events

On Cursor Node Changed

roam.events.on_cursor_node_changed({cb})

Description:

Register a callback when a cursor move results in the node under the cursor changing. This will also be triggered when the cursor moves to a position where there is no node.

Parameters:

{cb} triggered when the cursor moves to a different node or no node. Takes the node as an argument, or nil if no node.

Example:

local roam = require("org-roam")
roam.events.on_cursor_node_changed(function(node)
  if node then
    print("Node under cursor is " .. node.id)
  end
end)

Promise

As this plugin is built on top of nvim-orgmode, it has access to the utilities and follows the same methodology for asynchronous operations. To that end, the majority of APIs exposed by this plugin return an OrgPromise, which itself is a generic type such as OrgPromise<integer>.

-- All of our APIs return OrgPromise<...>
-- and the promise API is available via this import
local Promise = require("orgmode.utils.promise")

Resolve and Reject

A promise can either be resolved or rejected.

Resolution is a success and returns a value.
Rejection is a failure and can be caught.

-- If you have a value available, you can resolve/reject with it.
local resolved_promise = Promise.resolve(1234)
local rejected_promise = Promise.reject("error message")

Promise:next

With a promise, say of type OrgPromise<integer>, there are separate methods that can be used with it. The most important and common one is next, which takes a single function to apply to the result of the promise (in this case an integer), returning the new value or a new promise.

local promise = Promise.resolve(1234)

-- The function will be executed asynchronously when the promise's value
-- has been resolved. In the case of rejection, this function will NOT
-- be executed!
--
-- You can return anything from next()! It doesn't have to be the same type.
promise:next(function(value)
  return value + 100
end)

Promise:catch

Alongside next to handle promise resolution, there is also catch, which is used to map and operate on a promise’s error. Note that if catch is not used and the promise is rejected, it will throw an error message to the user within neovim.

local promise = Promise.reject("error message")

-- The function will be executed asynchronously when the promise's value
-- has been rejected. In the case of resolution, this function will NOT
-- be executed!
--
-- Nothing is returned from catch()!
promise:catch(function(err)
  print("Error: " .. err)
end)

Promise:finally

Beyond next and catch, the method finally can be used to invoke a function asynchronously after the promise is resolved or rejected.

It will occur regardless of whether next or catch are used, and can be leveraged to confirm that a promise has completed regardless of the outcome.

local promise = Promise.resolve(1234)

-- The function will be executed asynchronously when the promise
-- has finished.
--
-- Nothing is returned from finally()!
promise:finally(function()
  print("Done!")
end)

Promise:wait

Waits until the promise finishes. On resolving successfully, the value is returned by wait, otherwise on rejecting an error is thrown.

-- When a promise is resolved, it will return the value
local promise = Promise.resolve(1234)
assert(promise:wait() == 1234)

-- When a promise is rejected, it will throw an error
local promise = Promise.reject("error message")
local ok, msg = pcall(promise.wait, promise)
assert(not ok)
assert(msg == "error message")

Extensions

Dailies

Described here is the documentation for the dailies extension API. For the configuration, check out the section configuration -> extensions -> dailies for more details.

capture date

roam.ext.dailies.capture_date({opts})

Description:

Opens the capture dialog for a specific date. If no date is specified, will open a calendar to select a date.

Parameters:

{opts} optional table.
- date: optional, string or OrgDate. If a string, will parse YYYY-MM-DD format into a date. Otherwise, will use orgmode’s date type verbatim.
- title: optional, string representing the title to add to the capture buffer. Otherwise, will use YYYY-MM-DD for the title directive.

Returns:

A promise of string | nil, representing the id of the node created when captured, or nil when the capture was canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.capture_date({ date = "2024-04-27" }):next(function(id)
  if id then
    print("Captured node " .. id)
  end
end)

capture today

roam.ext.dailies.capture_today()

Description:

Opens the capture dialog for today’s date.

Returns:

A promise of string | nil, representing the id of the node created when captured, or nil when the capture was canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.capture_today():next(function(id)
  if id then
    print("Captured node " .. id)
  end
end)

capture tomorrow

roam.ext.dailies.capture_tomorrow()

Description:

Opens the capture dialog for tomorrow’s date.

Returns:

A promise of string | nil, representing the id of the node created when captured, or nil when the capture was canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.capture_tomorrow():next(function(id)
  if id then
    print("Captured node " .. id)
  end
end)

capture yesterday

roam.ext.dailies.capture_yesterday()

Description:

Opens the capture dialog for yesterday’s date.

Returns:

A promise of string | nil, representing the id of the node created when captured, or nil when the capture was canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.capture_yesterday():next(function(id)
  if id then
    print("Captured node " .. id)
  end
end)

find directory

roam.ext.dailies.find_directory()

Description:

Opens the roam dailies directory in the current window.

Example:

local roam = require("org-roam")
roam.ext.dailies.find_directory()

goto date

roam.ext.dailies.goto_date({opts})

Description:

Navigates to the note with the specified date. If no date is specified, will open a calendar to select a date.

Parameters:

{opts} optional table.
- date: optional, string or OrgDate. If a string, will parse YYYY-MM-DD format into a date. Otherwise, will use orgmode’s date type verbatim.
- win: optional, integer representing the handle of the window. If not specified, will open the note in the current window.

Returns:

A promise of OrgDate | nil, representing the date opened, or nil if canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_date({ date = "2024-04-27" }):next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

goto today

roam.ext.dailies.goto_today()

Description:

Navigates to today’s note.

Returns:

A promise of OrgDate | nil, representing the date opened, or nil if canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_today():next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

goto tomorrow

roam.ext.dailies.goto_tomorrow()

Description:

Navigates to tomorrow’s note.

Returns:

A promise of OrgDate | nil, representing the date opened, or nil if canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_tomorrow():next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

goto yesterday

roam.ext.dailies.goto_yesterday()

Description:

Navigates to yesterday’s note.

Returns:

A promise of OrgDate | nil, representing the date opened, or nil if canceled.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_yesterday():next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

goto next date

roam.ext.dailies.goto_next_date({opts})

Description:

Navigates to the next date based on the node under cursor.

If n is specified, will go n notes in the future. If n is negative, will go n notes in the past.

If there is no existing note within range that exists, nil is returned from the promise, and nothing happens.

Parameters:

{opts} optional table.
- n: optional, integer representing how many notes should be advanced. This is 1 by default. Can be negative.
- suppress: optional, boolean. If true, will suppress messages printed when navigating out of range.
- win: optional, integer. Handle of window where note should be opened, defaulting to the current window.

Returns:

A promise of OrgDate | nil, representing the date, or nil if out of range.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_next_date({ n = 2 }):next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

goto prev date

roam.ext.dailies.goto_prev_date({opts})

Description:

Navigates to the previous date based on the node under cursor.

If n is specified, will go n notes in the past. If n is negative, will go n notes in the future.

If there is no existing note within range that exists, nil is returned from the promise, and nothing happens.

Parameters:

{opts} optional table.
- n: optional, integer representing how many notes should be advanced. This is 1 by default. Can be negative.
- suppress: optional, boolean. If true, will suppress messages printed when navigating out of range.
- win: optional, integer. Handle of window where note should be opened, defaulting to the current window.

Returns:

A promise of OrgDate | nil, representing the date, or nil if out of range.

Example:

local roam = require("org-roam")
roam.ext.dailies.goto_prev_date({ n = 2 }):next(function(date)
  if date then
    print("Opened date " .. date:to_string())
  end
end)

Export

Unimplemented for now!

Graph

Unimplemented for now!

Protocol

Unimplemented for now!

Changelog

0.1.1

fix orgmode database now refreshes on roam node creation (#64)
feat selection dialog buffer now has a filetype of org-roam-select (#59)
fix type error when specifying config.bindings = false (#57)
feat allow to add more org file locations via an org_files list (#55)
chore add documentation for select buffer (#53)
fix dailies extension now opens the calendar at the current day (#48)
fix orgmode filetype is now detected open first opening buffer using find api
feat new keybinding prefix option to support changing across all keybindings (#47)
fix selection UI no longer wraps lines that are too long (#45)
chore unify formatting by providing a .editorconfig and adding stylua action (#44)
chore doc now recommends users specify tag for org-roam plugin

Credits

Kristijan Husak for creating nvim-orgmode (the backbone of functionality in neovim that we leverage)
Jethro Kuan for creating Org Roam (Emacs) (the original implementation whose design we copied)
Daniel Mendler for creating vertico.el (inspiration for our selection dialog)
Srinesh Nisala for creating nvim-window-picker (integrated directly for our window selection)
Dheepak Krishnamurthy for creating panvimdoc (used to create our vimdoc)

Files

DOCS.org

Latest commit

History

DOCS.org

File metadata and controls

Getting Started

Installation

lazy.nvim

packer.nvim

Configuration

directory

org_files

bindings

prefix

add alias

add origin

capture

complete at point

find node

goto next node

goto prev node

insert node

insert node immediate

quickfix backlinks

remove alias

remove origin

toggle roam buffer

toggle roam buffer fixed

database

path

persist

update on save

extensions

dailies

directory

bindings

capture date

capture today

capture tomorrow

capture yesterday

find directory

goto date

goto next date

goto prev date

goto today

goto tomorrow

goto yesterday

templates

ui

calendar

hl date exists

immediate

target

template

templates

ui

node view

focus on toggle

highlight previews

open

show keybindings

unique

Bindings

Dailies Extension

Modifying bindings

Coming from Emacs

Commands

RoamAddAlias

RoamAddOrigin

RoamRemoveAlias

RoamRemoveOrigin

RoamReset

RoamSave

RoamUpdate

User Interface

Org Roam Buffer

Select Buffer

Disable nvim-cmp completion in select buffer

API