orgmode-babel.nvim

orgmode-babel.nvim copied to clipboard

• orgmode-babel.nvim

An experimental plugin that evaluates and tangles code blocks in [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode]] using [[https://orgmode.org/worg/org-contrib/babel/][babel]] itself.

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

[[https://github.com/mrshmllow/BetterRecipeBook/assets/40532058/b1ca7384-4bb3-47d8-9148-b85f3a2ea54a][Demonstration]]

** Requirements

• [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode]]
• [[https://github.com/nvim-treesitter/nvim-treesitter][nvim-treesitter]]
• Neovim v0.9.0 or later
• A working ~emacs~ installation (does not require configuration)

** Setup

*** lazy.nvim

#+begin_src lua { "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 = {}

} }, #+end_src

*** Packer

#+begin_src lua 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 } #+end_src

** Usage

All commands accept a ~!~ to skip confirmation.

*** ~:OrgE[xecute]~

Evaluates every block in buffer.

See [[https://orgmode.org/manual/Working-with-Source-Code.html][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 [[https://orgmode.org/manual/Extracting-Source-Code.html][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 [[https://github.com/arnm/ob-mermaid][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.

#+begin_example git clone https://github.com/arnm/ob-mermaid ~/.../clone-location/ob-mermaid #+end_example

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