The pain... it won't stop. After so much oppression from other text editors, it's time we fight back. With the introduction of lua, we will fight back.
Introduction
Neorg is a plugin designed to help you manage your day-to-day life in ways you haven't thought of before. Think of this plugin as the ultimate way of making your life easier.
What this project is, and what it isn't
- This project is supposed to serve as an organizational tool for Neovim. It will run on the .norg file format - a revised, extensible and more computer friendly format compared to .org, all while retaining a decent amount of backwards compatibility with org (you will be able to convert between both formats).
- A foundation for developers to make their own extensions to the plugin and interface with other parts of user-contibuted code, known as modules (more info below)
- A full on competitor to emacs's org-mode
What this project isn't
- An org-mode clone - this project does not plan on fully cloning org mode in neovim. Rather, the goal of this repo is to take concepts from other organizational tools and reimagine them for the great text editor that neovim is. Expect a bit of familiarity but also a lot of changes, things tailored to the vim philosophy.
Installation
Using Packer
❗ Neorg requires plenary to operate, make sure to install it before you install neorg.
If you don't know what you're doing, just run this:
use { 'vhyrro/neorg', config = function()
require('neorg').setup {
load = {
['core.defaults'] = {} -- Load all the default modules
},
-- Tells neorg where to load community provided modules. If unspecified, this is the default
community_module_path = vim.fn.stdpath("cache") .. "/neorg_community_modules"
}
end, requires = { 'nvim-lua/plenary.nvim' }}If you want bleeding-edge features (may require Neovim HEAD):
use { 'vhyrro/neorg', branch = 'unstable', config = function()
...
end, requires = { 'nvim-lua/plenary.nvim' }}❗ NOTE: Neorg does not currently support actual org mode features (see usage questions below). The below code snippet is for people who are familiar with the structure of neorg.
use { 'vhyrro/neorg', config = function()
require('neorg').setup {
load = {
["your.module"] = { config = { ... } }
}
}
end}Don't understand the above code snippet? Check out the installation section of the GitHub Wiki.
Then run :PackerSync
WIP
As can be seen, this plugin is a work in progress - these magical features don't come out of nowhere, you know. Despite not providing any end-user features yet, it does provide an incredible foundation for developers willing to spend some time writing code for the plugin:
- The module system; the module system is an extensible way to manage and interface with code. Modules are pay-for-what-you-use tables that can get loaded and unloaded at will. They can subscribe to events using the powerful event system and can directly communicate with each other - they can even expose their own public APIs and configuration to be edited by the user. Example modules can be found here and a full tutorial for developing with modules can be found in the wiki.
- The event system; the event system is the way for said modules to communicate. Events can be broadcast to all subscribed modules or to individual modules as well, they can hold any sort of data you'd want to transport to another plugin, things like the current cursor position, line content etc. The choice is yours really.
Note that the neorg API may (and probably will be) subject to change! I'll try to refrain from breaking changes unless absolutely necessary, and will let developers know a while beforehand so they can update their modules. The API will stabilize after neorg becomes a bit more mature, so stick with me for now!
Usage Questions
A lot of people are asking about how to use neorg - so let me reinstantiate what can be seen in the WIP section.
Since neorg is a very young project there are currently no features for the end user yet. This means you can't insert your favourite headings and take notes just yet. The focus as of right now is on the core, the very foundation neorg is built on. Without a solid core, you can't make a solid plugin, correct? A weak core would also directly impact both the longevity and extensiblity, and we want this plugin to live for as long as possible :P
Don't get the impression that neorg will be forever like this, this is just where we are because the project isn't fully mature yet. You can expect this plugin to do everything org-mode can (and maybe even more!).
If you want a reference for the progress we have made so far, look at the roadmap. Optionally you can check out the github projects page too!
If there's anything you should know for now is that neorg (obviously) only triggers on .norg and .org files. So if you're testing your favourite module and nothing happens that might be a potential reason.
TL;DR: check out the roadmap. Also, all we need is just a little more time, sorry about that. For the latest and greatest check out the unstable branch :)
Consult The Wiki!
You can take a look at all the explanations in the official GitHub wiki!
Contributing
I really looove contributions! That's what this whole project is about - it's a really big plugin, so any help is appreciated ❤️. Don't know what to implement? Don't worry, a roadmap is available. The projects are pretty big there, so if you're truly stuck then you can always ask me personally!
Come chat with me on discord!
Also, if you love what I do and want to professionally support my work, boost development etc. drop me a few bucks will ya. Making this my job would be like a dream come true.
Links for the rich lads: