Repository files navigation

*This README is generated from./README.norg.

1. :Neorg templates fload journal (fload = force load: Overwritebuffer without asking)

2. AUTHOR, TODAY... will be automatically filled.

3. {TITLE_INPUT} is aninput_node with{TITLE} being the defaultplaceholder text.

• Changes the title.

1. Cursor at{WEATHER}.

• Choosing between options provided fromLuaSnip'schoice_node.

1. Cursor ends up at{CURSOR} position.

*{CURSOR} is a magic keyword, which specifies the last position ofthe cursor. More about magic keywords inMagicKeywords.

* You can use the same keyword in multiple places to insert the samecontent. Not possible in bareLuaSnip.

So, the plugin works like this. First you create a template file withplaceholders for dynamic values.

~/.config/nvim/templates/norg/journal.norg

@document.metatitle: {TITLE_INPUT}description:authors: {AUTHOR}categories:created: {TODAY}updated: {TODAY}version: 1.0.0@end* {TITLE_INPUT}  Weather: {WEATHER}  {{:{YESTERDAY}:}}[Yesterday] - {{:{TOMORROW}:}}[Tomorrow]** Daily Review   - {CURSOR}

When you load this plugin, you have the command::Neorg templates load journal.

This overwrites the current buffer and substitutes it with the contentthe template file. This behavior can be customized. More inSubcommands.

But do you see the{AUTHOR} placeholder in the template file?

Yes, it automatically substitutes those placeholderswith the power ofLuaSnip!

And since it is a snippet, you can also useinput_node,choice_nodeand all other useful nodes inside your template file! I've also addedsome useful snippets by default so you can use them out of the box.

• lazy.nvim installation

-- neorg.lualocalM= {"nvim-neorg/neorg",ft="norg",dependencies= {    {"pysan3/neorg-templates",dependencies= {"L3MON4D3/LuaSnip"} },-- ADD THIS LINE  },}

-- See {*** Options} for more optionsM.config=function ()require("neorg").setup({load= {      ["external.templates"]= {-- templates_dir = vim.fn.stdpath("config") .. "/templates/norg",-- default_subcommand = "add", -- or "fload", "load"-- keywords = { -- Add your own keywords.--   EXAMPLE_KEYWORD = function ()--     return require("luasnip").insert_node(1, "default text blah blah")--   end,-- },-- snippets_overwrite = {},      }    }  })end

Find details here:module.config.public

• string | string[]

Path to the directories where the template files are stored.

• Default:vim.fn.stdpath("config") .. "/templates/norg"

  • Most likely:~/.config/nvim/templates/norg

• Only looks for 1 depth.

• You may also provide multiple paths to directories with a table.

  • templates_dir = { "~/temp_dir1/", "~/temp_dir2/" }

• string

Default action to take when only filename is provided.

More details are explained inSubcommands

• Default:addSubcommands -add

• {KEY: <snippet_node>} |{KEY: fun(...) -> <snippet_node>}

Define snippets to be called in placeholders. Kyes are advised to beALL_CAPITALIZED.

• Examples are provided in./lua/neorg/modules/external/templates/default_snippets.lua

  • ReadBuiltin Snippets for more information.

• KEY should be the name of the placeholder

• Value should be a snippet node or a function that returns a snippetnode.

  • For exampleTITLE_INPUT needs to runM.file_title() right beforethe expansion. Therefore, it is defined with a function.

• First argument of nodes (pos) should always be1.

  • e.g.i(<pos>, "default text"),c(<pos>, { t("choice1"), t("choice2") })

  • The order of jumping is dynamically calculated after loading thetemplate, so you cannot specify with integer here.

• table<string, any>

Overwrite any field of./lua/neorg/modules/external/templates/default_snippets.lua.

• You might want to changedate_format.

  • For more tags, see:https://www.lua.org/pil/22.1.html

{snippets_overwrite= {date_format=[[%a, %d %b]]-- Wed, 1 Nov (norg date format)  }}

All command in this plugin takes the format of:Neorg templates <subcmd> <templ_name>.

• <subcmd>: Sub command. Basically defines how to load the templatefile.

• <templ_name>: Name of template file to load.

  • If you want to load<config.templates_dir>/journal.norg, call withjournal.

Readdefault_subcommand for more information. Ifyou ommit<subcmd> and call this plugin with:Neorg templates <templ_name>, the behavior depends on this configoption.

You can choose from the functions below.

Add (append) template file content to the current cursor position.

Force-load template file. Overwrites content of current file and replaceit with LuaSnip.

Load. Similar tofload but asks for confirmation before deleting thebuffer content.

Magic keywords take the format of{CURSOR}, same as a placeholder, buthas a special meaning.

The cursor position when the snippet ends.

• Same asi(0)

• If{CURSOR} is not found, the cursor will be at the end of the file.

Placeholder for metadata. Generated bycore.norg.esupports.metagen.

• Metadata will be simply substituted with this keyword.

• You cannot edit or control the output with this plugin.

  • ReadNeorg - Wiki -Metagen instead.

• This keywordMUST BE at thefirst line of the template file.

• In order to:Neorg inject-metadata blog-post, use{METADATA:blog-post}

If you are not familiar withLuaSnip, post what kind of snippet youwant! Maybe someone can help you out.

Post it in theDiscussionswith the category `✂️ Ask for a Snippet `.

nvim-neorg/neorg#714 (comment)

vim.api.nvim_create_autocmd("BufNewFile", {command="Neorg templates load journal",pattern= {neorg_dir.."journal/*.norg"},})

I will not list all builtin snippets but some useful ones that mightneed a bit of explanation. Please readdefault_snippets.luafor the whole list.

Inserts the file name.TITLE_INPUT would be an insert node withdefault text beingTITLE.

TODAY_OF_FILENAME will insert the date by parsing the filename.OF_FILENAME is useful whenjournal.strategy == "flat". So, if thefilename is2023-01-01.norg,YESTERDAY_OF_FILENAME => 2022-12-31.

Similarly,TODAY_OF_FILETREE is useful whenjournal.strategy == "nested". Ex: if the filename is/path/to/2023/01/01.norg,YESTERDAY_OF_FILETREE => 2022-12-31.

For more fine control, read2. Build you own snippetkey.

• pysan3

  • PluginSetup

  • PersonalKeywords

  • Templates

More examples welcome! Create a PR to update the README.

• Please follow code style defined in./stylua.tomlusingStyLua.

All files in this repository without annotation are licensed under theGPL-3.0 license as detailed inLICENSE.

No. This plugin heavily depends on luasnip and I do not have the timeand interest to support other ones.

There is anopen issuediscussing for a pure lua solution using autocmds.

There are other neovim template plugins (not just for norg) that do notdepend on luasnip. Here are some examples.

• template.nvim

• skeleton.nvim

• esqueleto.nvim

• new-file-template.nvim

• templar.nvim

Most of the code related to luasnip and template loading mechanism iswritten insidesnippet_handler.luawhichdoes not rely on neorg at all. The entry point is mostlyload_template_at_curpos(content, fs_name).

For usage example, read the implementation of subcommandshere.

You are free to fork / copy-paste this code as long as you respect theLICENSE. I just don't have the motivation to compete againstother template plugins listed above.

I'll be atneorg's discord server withthe username@pysan3, so feel free to ping me there.

Thank you very much but I'd be more than happy with a star for thisrepo. Buy yourself a cup of coffee and have a nice day 😉