orgmode-babel.nvim/README.md

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

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", ... }
  }
},

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.

:OrgT[angle] [name]

Tangles [name] block.

Advanced Configuration

Adding extra org-mode languages

Your emacs init.el will be sourced during execution of :OrgExecute and :OrgTangle, so packages you install there that provide extra babel languages will be available!

Follow the package's installation steps, and if they tell you to include it in org-babel-load-languages, additionally make sure that you include it in opts.langs.

1. Example

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

   First, lets create a ~/.emacs.d/init.el{.verbatim}.

   ; ~/.emacs.d/init.el
   
   ; Add the melpa package manager
   (require 'package)
   (add-to-list 'package-archives
     '("melpa" . "https://melpa.org/packages/") t)
   (package-initialize)
   
   ; Install ob-mermaid
   (unless (package-installed-p 'ob-mermaid)
     (package-install 'ob-mermaid))
   

   Then, in our plugin configuration, we can add mermaid to our opts.langs.

   {
     "mrshmllow/orgmode-babel.nvim",
     ...
     opts = {
       langs = { ..., "mermaid" }
     }
   },