Neorg - An Organized Future

Your New Life Organization Tool - All in Lua

Summary • Tutorial • Installation • Setup • Usage
Modules • Roadmap • Philosophy • FAQ

⚠️ Neorg 8.0.0 has introduced some breaking changes! Please see this blog post on how to migrate.

Summary

Neorg (Neo - new, org - organization) is a Neovim plugin designed to reimagine organization as you know it. Grab some coffee, start writing some notes, let your editor handle the rest.

What is Neorg?

Neorg is an all-encompassing tool based around structured note taking, project and task management, time tracking, slideshows, writing typeset documents and much more. The premise is that all of these features are built on top of a single base file format (.norg), which the user only has to learn once to gain access to all of Neorg's functionality.

Not only does this yield a low barrier for entry for new users it also ensures that all features are integrated with each other and speak the same underlying language. The file format is built to be expressive and easy to parse, which also makes .norg files easily usable anywhere outside of Neorg itself.

A good way of thinking about Neorg is as a plaintext environment which can be adapted to a variety of use cases. If a problem can be represented using raw text, it can be solved using Neorg.

❗ IMPORTANT: Neorg is young software. We consider it stable however be prepared for occasional breaking workflow changes. Make sure to pin the version of Neorg you'd like to use and only update when you are ready.

🌟 Tutorial

A video tutorial may be found on Youtube:

📦 Installation

Neorg's setup process is slightly more complex than average, so we encourage you to be patient :)

`rocks.nvim`

The recommended installation method is via rocks.nvim.

Installation snippet.

Run :Rocks install rocks-config.nvim (if you don't have it already!).
Run :Rocks install neorg.
Add the following to your config's lua/plugins/neorg.lua:
```
require("neorg").setup()
```

`lazy.nvim`

In order to install Neorg via lazy.nvim, you must take a few extra steps - this is because luarocks is a critical component for Neorg to function. See this blog for more information.

Important

Using luarocks Neorg will install itself and these dependencies with their respective versions:

lua-utils.nvim
nvim-nio
nui.nvim
plenary.nvim

Click for installation snippet.

Ensure you have vhyrro/luarocks.nvim installed:

{
    "vhyrro/luarocks.nvim",
    priority = 1000,
    config = true,
}

Add the following to your plugin list:

{
    "nvim-neorg/neorg",
    dependencies = { "luarocks.nvim" },
    lazy = false, -- Disable lazy loading as some `lazy.nvim` distributions set `lazy = true` by default
    version = "*", -- Pin Neorg to the latest stable release
    config = true,
}

`packer.nvim`

Neorg can be installed purely via luarocks on packer, pulling in all required dependencies in the process.

It is not recommended to use packer as it is now unmaintained.

Click for installation snippet.

use {
  "nvim-neorg/neorg",
  rocks = { "lua-utils.nvim", "nvim-nio", "nui.nvim", "plenary.nvim" },
  tag = "*", -- Pin Neorg to the latest stable release
  config = function()
      require("neorg").setup()
  end,
}

Other Plugin Managers

Because of the complexities of luarocks we are choosing not to supported other plugin managers for the time being. It is actively on our TODO list, however!

📚 Further Learning

After you have installed Neorg, we recommend you head over to either the Youtube tutorial series or to the wiki!

Credits

Massive shoutouts go to all the contributors actively working on the project together to form a fantastic integrated workflow:

mrossinek - for basically being my second brain when it comes to developing new features and adding new syntax elements
danymat - for creating the excellent foundations for the up and coming GTD system

And an extra thank you to:

Binx - for making that gorgeous logo for free!
bandithedoge - for converting the PNG version of the logo into SVG form

Support

Love what I do? Want to see more get done faster? Want to support future projects? Any sort of support is always heartwarming and fuels the urge to keep going ❤️. You can show support here:

Immense thank you to all of the sponsors of my work!