orgmode-babel.nvim

An experimental plugin that evaluates and tangles code blocks in nvim-orgmode using babel itself.

It uses emacs under the hood for perfect compatibility, but does not require you to add anything extra to your init.el.

demonstration.webm

Requirements

• nvim-orgmode
• nvim-treesitter
• Neovim v0.9.0 or later
• A working emacs installation (does not require configuration)

Setup

lazy.nvim

{
  "mrshmllow/orgmode-babel.nvim",
  dependencies = {
    "nvim-orgmode/orgmode",
    "nvim-treesitter/nvim-treesitter"
  },
  cmd = { "OrgExecute", "OrgTangle" },
  opts = {
    -- by default, none are enabled
    langs = { "python", "lua", ... },

    -- paths to emacs packages to additionally load
    load_paths = {}
  }
},

Packer

use {
  "mrshmllow/orgmode-babel.nvim",
  requires = {
    "nvim-orgmode/orgmode",
    "nvim-treesitter/nvim-treesitter"
  },
  cmd = { "OrgExecute", "OrgTangle" },
  opt = true,
  config = function ()
    require("orgmode-babel").setup({
      -- by default, none are enabled
      langs = { "python", "lua", ... },

      -- paths to emacs packages to additionally load
      load_paths = {}
    })
  end
}

Usage

All commands accept a ! to skip confirmation.

:OrgE[xecute]

Evaluates every block in buffer.

See Working with Source Code in the org manual.

:{range}OrgE[xecute]

Evaluate every block in range.

:OrgE[xecute] [name]

Evaluate [name] block.

:OrgT[angle]

Tangles whole file.

See Extracting Source Code in the org manual.

:{range}OrgT[angle]

Tangles all blocks in range. If the range is NOT %, the tangled file will likely only contain the contents of the last block, which is expected behaviour.

Advanced Configuration

Adding extra org-mode languages

Your emacs init.el will not be sourced during execution of :OrgExecute and :OrgTangle, so packages you install there wont be available.

However, orgmode-babel.nvim allows us to specify extra load paths, so we can make packages available that way.

Example

As an example, lets add ob-mermaid for mermaid functionality in orgmode-babel.nvim!

We have two options to get the package. We could either create an ~/.emacs.d/init.el and install it through a package manager, which will likely have a randomish name, or for the sake of simplicity and this being a neovim plugin, we can simply manually clone the repo to a known location.

git clone https://github.com/arnm/ob-mermaid ~/.../clone-location/ob-mermaid

{
  "mrshmllow/orgmode-babel.nvim",
  ...
  opts = {
    langs = { ..., "mermaid" }
    load_paths = { "~/.../clone-location/ob-mermaid" }
  }
},