/neorg

Modernity meets insane extensibility. The future of organizing your life in Neovim.

Primary LanguageLuaGNU General Public License v3.0GPL-3.0

Neorg - An Organized Future

Neovim Discord License Status

Your New Life Organization Tool - All in Lua

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


Summary

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.

❗ 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: Showcase image of a Neorg document
Concealing module enabled: Image of a Neorg document with the concealer module enabled.
First class treesitter support:

First class treesitter support

Treesitter powered editing:

Treesitter powered editing

Manage your tasks and projects with the GTD module:
  • See your current projects

See your current projects

  • Create a new task

Create a new task

  • Edit tasks in an efficient manner through the UI

Edit tasks in an efficient manner through the UI

And much more...

Powerpoint-like presentations in Neovim with the presenter module:

Powerpoint-like presentations in Neovim with the presenter module

Get syntax highlighting for any language supported by Neovim:

Plus fancy completion powered by nvim-cmp.

Get syntax highlighting for any language supported by Neovim

🔧 Installation

Neorg requires at least Neovim 0.6+ 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"
}

    If you don't want to always be on the bleeding edge version of Neorg you can use tags to slow down the rate at which you get features. You can 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's main treesitter parser is part of the nvim-treesitter repository, and can be installed through:

:TSInstall norg

If you want the parser to be more persistent across different installations of your config, make sure to set norg as a parser in the ensure_installed table, then run :TSUpdate. If you use the "maintained"/"all" parser collections then norg will be autoincluded.

In addition to the main parser you may also want to install additional subparsers which are injected into the norg parser. To do so, you want to run this code snippet before you invoke require('nvim-treesitter.configs').setup():

local parser_configs = require('nvim-treesitter.parsers').get_parser_configs()

-- These two are optional and provide syntax highlighting
-- for Neorg tables and the @document.meta tag
parser_configs.norg_meta = {
    install_info = {
        url = "https://github.com/nvim-neorg/tree-sitter-norg-meta",
        files = { "src/parser.c" },
        branch = "main"
    },
}

parser_configs.norg_table = {
    install_info = {
        url = "https://github.com/nvim-neorg/tree-sitter-norg-table",
        files = { "src/parser.c" },
        branch = "main"
    },
}

Then run :TSInstall norg_meta norg_table.

Here's an example config for nvim-treesitter, yours will probably be different:

require('nvim-treesitter.configs').setup {
    ensure_installed = { "norg", "norg_meta", "norg_table", "haskell", "cpp", "c", "javascript", "markdown" },
    highlight = { -- Be sure to enable highlights if you haven't!
        enable = true,
    }
}

Troubleshooting Treesitter

  • Having a rare occurence where the parser doesn't work instantly? Try running :e. Still not working? Uh oh, you're stepping on muddy territory. There are several reasons why a parser may not work right off the bat, however most commonly it's because of plugin loading order. Neorg needs nvim-treesitter to be up and running before it starts adding colors to highlight groups.
  • Not using packer? Make sure that Neorg's setup() gets called after nvim-treesitter's setup.
  • If you're on Mac and have compilation errors when doing :TSInstall, check out this fix.

📦 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

We recommend reading the spec and familiarizing yourself with the new format. 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.

List of Core Modules:
Module name Description
core.gtd.base Manages your tasks with Neorg using the Getting Things Done methodology.
core.norg.completion A wrapper to interface with several different completion engines.
core.norg.concealer Enhances the basic Neorg experience by using icons instead of text.
core.norg.dirman This module is be responsible for managing directories full of .norg files.
core.norg.journal Easily create files for a journal.
core.norg.qol.toc Generates a Table of Contents from the Neorg file.
core.presenter Neorg module to create gorgeous presentation slides.

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"] = {},
    }
}
List of community modules:
Module name Description
core.integrations.telescope Neorg integration with Telescope
external.gtd-project-tags Provides a view of tasks grouped with a project tag. Requires core.gtd.base
external.integrations.gtd-things Use Things3 database to fetch and update tasks instead. Requires core.gtd.base

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