Neorg - An Organized Future

Your New Life Organization Tool - All in Lua

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

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

Why do we need Neorg?

There are currently projects designed to clone org-mode from emacs, then what is the goal of this project?

Whilst those projects are amazing, it's simply not enough for us. We need our own, better solution - one that will surpass every other text editor. It's through our frustration of no native solution for Neovim and inconsistencies in the most popular markup formats that Neorg was born.

To learn more about the philosophy of the project check the philosophy section.

:exclamation: IMPORTANT: Neorg is alpha software. We consider it stable however be prepared for changes and potentially outdated documentation. We are advancing fast and while we are doing our best to keep the documentation up-to-date, this may not always be possible.

🌟 Showcase

A `.norg` file:

Concealing module enabled:

🔧 Installation

Neorg requires at least Neovim 0.7+ to operate.

You can install it through your favorite plugin manager:

• Packer:

  use {
      "nvim-neorg/neorg",
      config = function()
          require('neorg').setup {
              ... -- check out setup part...
          }
      end,
      requires = "nvim-lua/plenary.nvim"
  }
  

  Every time Neorg hits a new release, a new tag is created by us, so you don't have to worry about all the updates inbetween. That means, adding tag = "*" in Packer will update to latest stable release.

  You can also pin Neorg to one specific version through e.g. tag = "0.0.9".

• Packer (with lazyloading):

  Want to lazy load? Know that you'll have to jump through some hoops and hurdles to get it to work perfectly. You can use the ft key to load Neorg only upon entering a .norg file:

  use {
      "nvim-neorg/neorg",
      -- tag = "latest",
      ft = "norg",
      after = "nvim-treesitter", -- You may want to specify Telescope here as well
      config = function()
          require('neorg').setup {
              ...
          }
      end
  }
  

  Although it's proven to work for a lot of people, you might need additional setups depending on how your lazyloading system is configured.

  One important thing to ask yourself is: "is it really worth it?". Neorg practically lazy loads itself: only a few lines of code are run on startup, these lines check whether the current extension is .norg, if it's not then nothing else loads. You shouldn't have to worry about performance issues when it comes to startup, but hey, you do you :)

• vim-plug:

  Plug 'nvim-neorg/neorg' | Plug 'nvim-lua/plenary.nvim'
  

  You can then put this initial configuration in your init.vim file:

  lua << EOF
  require('neorg').setup {
      ...
  }
  EOF
  

Treesitter

Be sure to have nvim-treesitter installed on your system for this step!

Neorg will automatically attempt to install the parsers for you upon entering a .norg file if you have core.defaults loaded. A command is also exposed to reinstall and/or update these parsers: :Neorg sync-parsers.

Note that the :Neorg sync-parsers command is only available when in a .norg file, and the installation isn't reproducible. To make it permanent, you want to alter your treesitter configuration a little:

require('nvim-treesitter.configs').setup {
    ensure_installed = { "norg", --[[ other parsers you would wish to have ]] },
    highlight = { -- Be sure to enable highlights if you haven't!
        enable = true,
    }
}

NOTE: Putting "norg_meta" into your ensure_installed table may trigger unintended errors. This is because norg_meta isn't in the native nvim-treesitter repositories, and the parser is only defined while using Neorg. This is why using :Neorg sync-parsers is recommended.

Troubleshooting Treesitter

• Not using packer? Make sure that Neorg's setup() gets called after nvim-treesitter's setup.
• If on MacOS, ensure that the CC environment variable points to a compiler that has C++14 support. You can run Neovim like so: CC=/path/to/newer/compiler nvim -c "TSInstallSync norg" in your shell of choice to install the Neorg parser with a newer compiler. You may also want to export the CC variable in general: export CC=/path/to/newer/compiler.

📦 Setup

You've got the basic stuff out the way now, but wait! That's not all. You've installed Neorg - great! Now you have to configure it. By default, Neorg does nothing, and gives you nothing. You must tell it what you care about!

Default modules

Neorg runs on modules, which are discussed and explained in more depth later on. Each module provides a single bit of functionality - they can then be stacked together to form the entire Neorg environment.

The most common module you'll find is the core.defaults module, which is basically a "load all features" switch. It gives you the full experience out of the box.

The code snippet to enable all default modules is very straightforward:

require('neorg').setup {
    load = {
        ["core.defaults"] = {}
    }
}

You can see here which modules are automatically required when loading core.defaults.

⚙ Usage

A new and official specification is in the works, we recommend reading it here. You can view a summary directly in your neovim instance by running :h neorg if you don't like reading a lot!

Afterwards it's as simple as hopping into a .norg file and typing away.

A good first step is to require the core.norg.dirman module, it'll help you manage Neorg workspaces. Workspaces are basically isolated directories that you can jump between:

require('neorg').setup {
    load = {
        ["core.defaults"] = {},
        ["core.norg.dirman"] = {
            config = {
                workspaces = {
                    work = "~/notes/work",
                    home = "~/notes/home",
                }
            }
        }
    }
}

Changing workspaces is easy, just do :Neorg workspace work, where work is the name of your workspace. Note that :Neorg is only available when the Neorg environment is loaded, i.e. when you're in a .norg file or have loaded a .norg file already in your Neovim session.

If the Neorg environment isn't loaded you'll find a :NeorgStart command which will launch Neorg and pop you in to your last (or only) workspace.

It works, cool! What are the next steps?

We recommend you add some core modules that can greatly improve your experience, such as:

• Using the concealer module to enable icons (core.norg.concealer)
• Setting up a completion engine (core.norg.completion)

Setting these up is discussed in the wiki, so be sure to check there!

You're now basically set! The rest of this README will be additional information, so keep reading if you care about what makes Neorg tick, or you want to genuinely get good at using it.

🥡 Modules

As you saw previously, we loaded core.defaults and recommended that you load core.norg.dirman. As you probably know those are modules. But what are they, exactly?

Modules are basically isolated bits of code that provide a specific subset of features. They can be docked into the environment at any time and can be essentially stacked together like lego bricks! They can bind themselves to events and callbacks and communicate with each other.

To require a module, just do:

require('neorg').setup {
    load = {
        -- Require the module with the default configurations for it
        ["your.required.module"] = {},

        -- Require the module, and override the configurations (with the "config" table)
        ["your.required.module"] = {
            config = {
                some_option = true
            }
        }
    }
}

As always, for a little more info you can consult the wiki page here. To know which configurations are provided by default for a module, just click on their link: you'll go to the module page in the wiki.

Core Modules

Here is a list of core modules that aren't part of core.defaults and can be added individually by you.

Feel free to try by adding them to your Neorg setup.

External Modules

Users can contribute and create their own modules for Neorg. To use them, just download the plugin with your package manager, for instance with Packer:

use {
    "nvim-neorg/neorg",
    requires = "john-cena/cool-neorg-plugin",
}

After that it's as easy as loading the module it exposes normally:

require('neorg').setup {
    load = {
        ["cool.module"] = {},
    }
}

If you ever end up making a module for Neorg feel free to make a pull request and add it to this README!

❓ Philosophy

Our goals are fairly simple:

1. Revise the org format: simple, extensible, unambiguous. Will make you feel right at home. Alternate markup formats have several flaws, but the most notable one is the requirement for complex parsers. I really advise checking some writeups out on how bad it can get at times. What if we told you it's possible to alleviate those problems, all whilst keeping that familiar feel? Enter the .norg file format, whose base spec is practically complete. The cross between all the best things from org and the best things from markdown, revised and merged into one.

2. Keybinds that make sense: vim's keybind philosophy is unlike any other, and we want to keep that vibe. Keys form a "language", one that you can speak, not one that you need to learn off by heart.

3. Infinite extensibility: no, that isn't a hyperbole. We mean it. Neorg is built upon an insanely modular and configurable backend - keep what you need, throw away what you don't care about. Use the defaults or change 'em. You are in control of what code runs and what code doesn't run!

4. Logic: everything has a reason, everything has logical meaning. If there's a feature, it's there because it's necessary, not because two people asked for it. If something has a more niche use case, it should be documented.

🗺 Roadmap

We track a high-level roadmap, so that you can know what to expect. Just do :h neorg-roadmap. To know exactly what's being worked on, just check out the repo's PRs.

📚 FAQ

The wiki is the go-to place if you need answers to anything Neorg-related. Usage, Keybinds, User Callbacks, Modules, Events? It's all there, so we recommend you seriously go read it!

Contributing

Have an idea? An improvement to existing functionality? Feedback in general?

We seriously recommend you join our discord to hang out and chat about your ideas, plus that you read the CONTRIBUTING.md file for more info about developer-related stuff!

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 GTD workflow in Neorg that we literally use internally to plan new features

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 :heart:. You can show support here:

• Buy me a coffee!
• Support me on LiberaPay
• Donate directly via paypal
• Support me on Patreon
• Donate to my monero wallet: 86CXbnPLa14F458FRQFe26PRfffZTZDbUeb4NzYiHDtzcyaoMnfq1TqVU1EiBFrbKqGshFomDzxWzYX2kMvezcNu9TaKd9t
• Donate via bitcoin: bc1q4ey43t9hhstzdqh8kqcllxwnqlx9lfxqqh439s