Literate Neovim config (literate)
Stability: experimental (org-extensions-stability)
literate makes an org file your Neovim configuration: saving it tangles its Lua blocks and runs the ones you changed, so a new option or keymap works at once, and a block's error shows on its line in the org file.
require("org").setup({
extensions = { literate = { files = { "~/.config/nvim/init.org" } } },
})
A literate file is one of files (paths or globs; default stdpath("config")/init.org) or, with detect, an org file under a directory of allow (default: stdpath("config")) whose Lua blocks tangle by default:
#+PROPERTY: header-args:lua :tangle lua/config.lua :mkdirp yes
* Options
#+begin_src lua
vim.o.relativenumber = true
#+end_src
Trust
Saving a literate file runs Lua in your Neovim and writes the files its blocks tangle to, so it happens only for files you chose:
- the files in
filesare trusted; - a detected file must be under
allow, and withconfirm(default) the first save asks whether to tangle and run it; the answer is kept instdpath("data")/org/literate-trust.json(delete its entry to be asked again); - any other org file with a
:tangleheader (a file you downloaded, a repository you cloned) is saved like any org file: nothing is tangled or run.
Opening a literate file runs and evaluates nothing: what it holds is remembered as text (noweb and :var references, which can evaluate blocks, are expanded only when a trusted file is tangled). literate_goto_org only looks at trusted files. The actions below work on the current buffer when you run them, like :Org tangle or executing a block.
Saving it
When a literate file is written it is tangled with org-babel tangle (so :tangle, :noweb, :comments... work as usual) and, with reload, the Lua blocks whose text is new since the last tangle (or since the file was opened) run in file order, in this Neovim, and so do the blocks whose tangled text changed (a block they include with noweb was edited). Blocks you did not touch don't run again. An error while tangling is reported once per save and never interrupts the write. An error, at compile or run time, is a diagnostic on the org line it comes from (for an error raised in a function the block calls, such as vim.o.nosuchoption = 1, the line of the call) (diagnostics), and in the quickfix list with quickfix; a block that failed runs again on the next save until it works. A notification says what was tangled and reloaded.
Actions
literate_reload | run the Lua block at point, or every tangled Lua block of the file outside one |
literate_run_block | run the Lua block at point (tangled or not) and show the value it returns |
literate_health | compile every Lua block without running it; syntax errors become diagnostics |
literate_goto_org | in the tangled file: jump to the org line the cursor's line comes from, by the link comments of :comments link, else by matching the text in the blocks that tangle to this file |
literate_bootstrap | :Org literate_bootstrap [path] writes an init.lua (default: next to the org file) for the pattern below |
Bootstrapping
Neovim reads init.lua, not init.org. Tangle the blocks to another file (lua/config.lua) and let :Org literate_bootstrap write an init.lua that loads it. On startup that init.lua re-tangles init.org first when it is newer than the tangled file (edited on another machine or pulled with git), with a small tangler of its own (org.nvim is not loaded yet). It keeps the lua blocks whose :tangle is the tangled file, taking :tangle and :noweb from the block, else the nearest heading's header-args:lua / header-args property, else #+PROPERTY, and expands <<name>> references when :noweb is yes, tangle, no-export or strip-export. It does not evaluate anything: no :var, no Lisp in header arguments, no <<name()>> results, no :prologue; use saving in Neovim (the full tangle) for those. If it fails, it says so and loads the tangled file it has. Then it runs the tangled file. Blocks tangled to other files are not loaded by the stub. So the setup is:
~/.config/nvim/init.org the configuration
~/.config/nvim/lua/config.lua tangled from it (on save)
~/.config/nvim/init.lua the stub (written once)
org.nvim itself is set up from the tangled file like any plugin, with the literate extension on so the next save tangles again.
Options
files | literate org files (stdpath("config")/init.org) |
detect | also files with header-args:lua :tangle (true) |
allow | directories detect looks in ({ stdpath("config") }) |
confirm | ask before the first save of a detected file (true) |
tangle_on_save | tangle when written (true) |
reload | run the changed Lua blocks (true) |
diagnostics | errors as diagnostics (true) |
quickfix | errors in the quickfix list too (false) |
notify | report what was tangled and run (true) |
bootstrap_file | init.lua of literate_bootstrap (next to the org file) |