Repository files navigation

**PRE-ALPHA** - breaking changes incoming soon.

Super basic capture module for neorg, for capturing notes referring to code.

I just wanted to capture a TODO with a popup, which captures the file/line, and itsassociated git URL. It can also capture a git-diff for a file.

It's a little neorg module, but it's also a little vim plugin which does the capturing(typically, outside of neorg) & then invokes the module.

NOTE: this began just as a quick hack while the neorg-gtd feature is unavailable.Maybe this will eventually be superceded or reworked on top of GTD.

Given a fileneorg/lua/neorg.lua with the following content in your git repo,selected in visual mode:

--- Returns whether or not Neorg is loaded---@returnbooleanfunctionneorg.is_loaded()returnconfiguration.startedend

With the default mapping of<leader>ccv (mapped torequire'codecap'.cap('n', { inbox = 'vsplit' })), you would firstSee a single-line popup, where you might enter "Investigate is_loaded.",and press<cr>.

You'd see a new vsplit showing$workspace/inbox.norg, with the following content(imagine the| is the cursor).

* Inbox- ( ) Investigate is_loaded.|@code lua--- Returns whether or not Neorg is loaded---@return booleanfunction neorg.is_loaded()    return configuration.startedend@endSee {https://github.com/nvim-neorg/neorg/blob/main/lua/neorg.lua#L130-L134}[neorg.lua#L130-L134]

The git link is produced by gitlinker.nvim. If the file weren't in git, then you'dsee a file link instead.

Defaults mappings are as follows:

To keep these default, just callsetup({}) with an empty table:

require'codecap'.setup({})

You can override them when you setupcodecap. Theseapply normal/visual mode mappings as appropriate for each command:

require'codecap'.setup({mappings= {    ['<leader>ccv']='vsplit',    ['<leader>ccs']='split',    ['<leader>cce']='edit',    ['<leader>ccn']='noshow',    ['<leader>ccc']='inbox',    ['<leader>ccd']='diff',}})

Setmappings = {} if you don't want any mappings.

require'codecap'.setup({mappings= {} })

You can define a mapping like:require'codecap'.cap('n', { inbox = 'vsplit' })

• 'n' or'v' for normal/visual mode.
• { inbox = 'vsplit' }, to dictate whether to displaythe inbox.

Thecodecap.cap() function invokesgitlinker and then uses the result [or noresult] to invoke neorg commands.

• :Neorg codecap inbox - opens your inbox file. It's just for convenience.I recommend linking to the inbox from yourindex.norg.

By themselves, the neorg module's capturing commands don't have gitlinker support.(You need to invokecodecap.cap() as above for the gitlinker support).

• First parameter is the vim mode (n orv).

• If a URL is passed in as an additional parameter,(whichrequire'codecap'.cap(...) would do for you), then that is transformedinto a link.

• If no URL is passed to theseedit/vsplit/split/noshow commands, they createa link with a file reference instead. The link refers to the file & line numberof the current buffer.

• :Neorg codecap [vplit|edit|split|noshow] - open a small popup where you entera todo. The todo ends up in a workspace file calledinbox.norg. The differentsubcommands dictate whether & how to show the todo in the inbox.

• :Neorg codecap diff - similar toedit except it captures a diff of the wholefile, and it only works innormal mode.

• Neorg can't currently open a file link with a line number{/ file.txt:23}.SeePR - hopefully soon.
• The norg spec for file links doesn't support line number ranges, yet. Sofile links will just show the first line.

• key mappings (visual, normal modes).
• Maybe variants on the same cap func.
  • copying actual code blocks, not just gitlinks / file links.
  • opening the inbox as you capture. Split,etc.
  • Tagging with a date.
• Hopefully I'll add a visual mode command to enter the selected filename+linenumsinto the todo entry.
• capture git-diffs?
• Maybe a separate module for refiling/organising. Depends on GTD progress.

First, you need a recent neovim, neorg and gitlinker.

• Neorg.
• Gitlinker.

You can install them all through your favorite vim plugin manager.

Something like this but this is WIP(I use lazy.nvim so other samples might not actually work)

• lazy.nvim

  require("lazy").setup({    {"nvim-neorg/neorg",opts= {load= {                ["core.defaults"]= {},...                ["external.codecap"]= {},            },        },requires= {"nvim-lua/plenary.nvim","ruifm/gitlinker.nvim",          {"laher/neorg-codecap",keys= {-- indicates to lazy to load the plugin-- the mappings themselves are defined/overridden by codecap iteslf                  {'<leader>cce',desc='capture a thing. open with :edit',mode= {'v','n'} },                  {'<leader>ccv',desc='capture a thing. open inbox with :vsplit',mode= {'v','n'} },                  {'<leader>ccs',desc='capture a thing. open inbox with :split',mode= {'v','n'} },                  {'<leader>ccn',desc='capture a thing. do not open inbox',mode= {'v','n'} },                  {'<leader>cci',desc='open inbox',mode= {'n'} },                  {'<leader>ccd',desc='capture git-diff of current file. open inbox',mode= {'n'} },              },config=function()require'codecap'.setup({})end          },       },    },})

• vim-plug

  Plug'nvim-neorg/neorg' | Plug'nvim-lua/plenary.nvim' | Plug'ruifm/gitlinker.nvim' | Plug'laher/neorg-codecap'

  You can then put this initial configuration in yourinit.vim file.

  TODO test the setup, add override key mappings.

  lua << EOFrequire('neorg').setup {  load= {      ["core.defaults"]= {},...      ["external.codecap"]= {},  },}-- codecap.setup will ssetup default mappings.-- codecapkey mappings operate outside of neorg,so they are mapped outside too.require('codecap').setup {}EOF