orgmode-babel.nvim/README.org

* 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