Unofficial Notes and Resources on Neorg

While diving into the Neorg project, I have accumulated a number of notes and links. As with any large project, it takes a while to get oriented, and sometimes it is beneficial to see someone else's notes. Due to the open-source nature of the project, it is especially useful to keep a collection of all relevant links in one place.

Disclaimer

This site does not constitute official documentation, nor are these notes endorsed by any person or organization. These are my personal notes that I wrote while getting oriented with Neorg, and I have chosen to make them public in the hope that someone else may find them useful.

Project Description

From the official README:

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.

Neorg is a plugin to extend the functionality of the Neovim editor, but the scope of the project is considerably wider. It defines a new file format, .norg and extensions are currently in the works to support databases, syncing, mobile, and more.

In the words on mrossinek:

Neorg is a life organization tool for Neovim. It implements its own plain-text format improving upon others such as markdown and org-mode by leveraging the full power of Treesitter and combined with Lua revolutionizes note taking in Neovim.

Installation

Basic installation

Installation with Docker

Installation with Nix (best option)

Basic

See the official README.

Installation with Docker

docker pull yelircaasi/neorg-basic:latest

WIP: need to push image and dockerfile, also pin commits to make everything even more solid

Installation with Nix (best option)

# TODO

Norg Files

Cheatsheet

1.0 Specification

1.0 Semantics

Standard Library (.norg)

Standard Library (Janet)

Usage

Config Examples

WIP

Config Examples

Doom Neovim

asn/dotfiles

katawful/dotfiles-nvim

max397574/omega-nvim

Jxstxs/nvimconf

Porting neovim config to lua (blog post with example)

janlaff/linux-dotfiles

Modules

The wiki already has good documentation of the built-in modules. This page will be mostly for my own notes on the modules - insights, questions answered, thoughts, and so on.

Tutorial on making modules

Tutorial on making modules, with accompanying videos:

Extending Neorg - Your first module
- video
- .md
Extending Neorg - Module configuration and overview
- video
- .md
Extending Neorg - A treesitter-powered module
- video
- .md

Example of a 3rd-party module

neorg-telescope

WIP: find examples on configs using this

Ecosystem Overview

Neorg Core

WIP

Neorg Extensions

WIP

How the Neorg API works

WIP

Roadmaps

Neorg Roadmap

GTD Module Roadmap

also relevant: older notes
see also this section of the main Neorg roadmap Groen Roadmap (mobile app)

Norgberg Roadmap

see also this section of the main Neorg roadmap

Zettelkasten Tracking Issue

Active Projects

Foundational

Official Wiki - official documentation of Neorg
Main Github Repo - the mother ship
norg-specs - the official specification of Norg file syntax and semantics: the One Source of Truth
neorg-dirman - a directory manager for Neorg, a core module which provides a basic interface for workspaces

Parsers, Treesitter

zig-norg - Norg parser written in zig; an API to interface with the .norg file format
rust-norg - rust version of zig-norg
neorg-breeze - rust library for parsing entire directories of Norg files in a multithreaded fashion
neorg-haskell-parser - reimplementation of the parser with the Neorg markup specification. It will be able to transform .norg files to the pandoc AST and subsequently to the plethora of formats that pandoc supports
Norg.jl - a Julia parser for .norg files, currently targeting HTML
norg.py - Python Norg parser, still immature
tree-sitter-norg-meta -
tree-sitter-norg2 -
tree-sitter-norg -

Tools and Extensions

norg-fmt - a formatter for Neorg, written in Zig and currently dormant but not dead; to be rewritten in Python
neorg-templates -
neorg-exec -
GTD module - see roadmaps
Taskwarrior integration - apparently dormant project here;

Neorg Beyond Neovim

Norgberg - database services module
norgopolis - a lightweight communication, launcher and utility services client for the Neorg rust-native modules ecosystem on desktop
Groen - "neorg mobile app inspired by Obsidian" - developed with Flutter (still in embryo)
- also has potential for general web usage, via Flutter for the web

Other

nixpkgs-neorg-overlay - required to install recent version with the Nix package manager

Project Ideas

parser in {{language}}

The more the merrier. As noted here, "many parsers can be created for it without forming annoying "'dialects'".

Graph Visualization

→ something like the graph visualization feature of Obsidian

Improve Internationalization (i18n)

Almost goes without saying in an open-source project, but it bears saying anyway.

*TeX Support

Orgmode can do this, why can't we?

Advanced date and time support

Likely best implemented as a core module?

neorg-planager (my personal obsession at the moment)

A module for as-declaratively-as-possible creating Gantt timelines and schedules from roadmaps, projects, and tasks. Designed to take care of most of the "what" and "when" and "how" up front so as to reduce cognitive load. Ideally, this will take care of ensuring that day-to-day time usage aligns with long-term priorities. Generally in line with the GTD methodology, but tailored to my needs. Robustness to unforeseen circumstances and ability to track completion and view statistics (a bit like Anki, perhaps) are essential.

One of the biggest features is the ability to use custom priority-respecting scheduling algorithms to go from roadmaps, Gantts, projects, etc. to fine-grained schedules, and also to have this accessible through my phone (for now via Telegram API, later via Signal API or even a custom App).

Contributing

Contributing to these notes

If you find something is missing or incomplete, fork the repo and open a pull request, or open an issue.

Contributing to Neorg

See this official document.

Get in touch with the author. As always, the Discord server is a good place to discuss ideas (or anything, really).

Helpful Resources

Discord Server (very lively and welcoming)

Tutorials

Notable people

Note: this is not a comprehensive list by any means, and I do not wish to offend anyone who is a key contributor to the project whose name I missed. Just make a pull request or open an issue, and I'll make sure you get included.

Vhyrro - creator of Neorg
- Github
mrossinek
- Github
NTBBloodbath
- Github
Sevoris
- Github
danymat
- Github
max397574
champignoom
JoeyGrajciar
danilshvalov
andreadev-it
laher
pysan3
Gilfoyle
Marmalade
Bryant
Sir Polo Modulus III

Background Knowledge

This covers some of what I would consider useful to know when working with Neorg & co. Most of the sections are in the form of 'learning roadmaps' - some key readings to get up to speed, sometimes also activities or questions to guide one's acquisition of the material.

Markdown

Markdown Guide
Markdown Tutorial
Learn Markdown in Y Minutes - available in many different languages here
the official documentation, as needed

emacs orgmode

Org mode beginning at the basics
Org Mode Compact Guide - reading Emacs Lisp isn't too bad if you have had any exposure to a lisp-family language before, and if not, this will will help you make sense of it
.org File Syntax Specification

Neovim

General

WIP

Plugins

WIP

Treesitter

nvim-treesitter

WIP

Programming Languages

Multilinugual

Good selection of problems from Rosetta Code

Lua

Why Lua?
A Look at the Design of Lua
Hyperpolyglot - comparison with other scripting languages, see here for the same examples in 4 more languages
Learn Lua in Y Minutes
nvim Lua guide - excellent tutorial

Janet

Learn Janet in Y Minutes
Official Site - read the main page and skim the documentation
Community Docs - browse and search examples

Scheme

Scheme is Fun - quick video on Scheme syntax
decent short intro
longer intro
Learn Racket in Y Minutes - Racket is closely related to Scheme, so this is a good way to get a feel for the language - just don't memorize all the the details here; focus on generalities
nice little video course
Official Guide - very well-written and worth reading - not too long
Cookbook - one of the better ways to get a feel for the language
Teach Yourself Scheme in Fixnum Days - probably more than is needed for the small amount of Scheme used in Neorg, but well-written and worth leafing through

Zig

Why Zig When There is Already C++, D, and Rust? - to get motivated
ziglearn.org
Learn Zig in Y Minutes
In-depth Overview - really nice read
Zig Docs - worth skimming
Examples - to get a practical feel for the language

Rust

Learn Rust in Y Minutes
Hyperpolyglot
The Rust Programming Language - the Bible of Rust, worth at least skimming
Rust by Example - my preferred way to learn, especially when a language is new to me
The Rust Cookbook - another nice format, and the third member of the Holy Trinity of Rust books

Haskell

Learn Haskell in Y Minutes - worth going through for exposure to Haskell syntax
Hyperpolyglot - good examples of basic tasks, even if the other 3 languages are unfamiliar
Learn You a Haskell for Great Good - a classic
Happy Learn Haskell Tutorial - another highly recommended resource
Real-World Haskell - worth going through to solidify what has already been learned and to go from theory to practice

Dart (→ Flutter)

FreeCodeCamp - very basic
Another quick 1-page intro

GTD Framework

Wikipedia - good concise overview
Official site - 5 Steps
a GTD implementation in Orgmode
GTD in Taskwarrior - interesting tutorial series

Zettelkasten System

Wikipedia - as always, Wikipedia has an excellent introduction
Zettelkasten 101 (good blog post)

Parsing and Formal Language Theory

James Power Notes - impressively concise and readable

WIP: Read through and sort

Great discussion of productivity

Selected Rosetta Code Problems

A+B

Arithmetic/Integer

Arrayconcatenation

Array length

Arrays

Boolean values

Call a function

Character codes

Check that file exists

Code Golf: Code Golf

Compare length of two strings

Conditional structures

Conjugate a Latin verb

Copy a string

Create a file

Detect division by zero

Determine if a string is numeric

Draw a pixel

Empty program

Empty string

Environment variables

Even or odd

Factorial

File input/output

Find limit of recursion

Find square difference

FizzBuzz

Formatted numeric output

Function definition

Greatest element of a list

Halt and catch fire

Hello world/Graphical

Hello world/Text

Increment a numerical string

Input loop

Integer comparison

Iterators

Jump anywhere

Keyboard input/Flush the keyboard buffer

Keyboard input/Keypress check

Keyboard input/Obtain a Y or N response

Literals/Integer

Logical operations

Loops/Break

Loops/Do-while

Loops/Downward for

Loops/For

Loops/For with a specified step

Loops/Increment loop index within loop body

Loops/Infinite

Loops/N plus one half

Loops/While

Loops/With multiple ranges

Multiplication tables

Naming conventions

Nth root

Null object

Operator precedence

Program termination

Read a file line by line

Real constants and functions

RPG attributes generator

Selectively replace multiple instances of a character within a string

Sieve of Pritchard

Simple windowed application

Split a character string based on change of character

String append

String comparison

String concatenation

String interpolation_(included)

String matching

String prepend

Substring

System time

Tokenize a string

Transliterate English text using the Greek alphabet

Two's complement

User input/Text

Variables

Zero to the zero power

Comparison with Similar Projects

Markdown

WIP

emacs orgmode

The OG superuser everything-in-one plugin for the OG superuser everything-in-one editor (i.e. operating system).

Mature Ecosystem, most notably:

WIP

Obsidian

Verdict: A beautiful and very useful product whose main flaw is not being open-source. Has a powerful ecosystem and good design, and is built around markdown.

Joplin

WIP

mind.nvim

Notable features

tree-based
pure lua (nvim plugin)
designed to support a variety of workflows, such as journaling, note-taking, personal wiki, task management

... an organizer tool for Neovim. It can be used to accomplish and implement a wide variety of workflows. It is designed to quickly add items in trees. Why a tree? Well, list of things like WIP lists are great but they lack the organization part. Most of them can be gathered in “lists of lists” — you probably have that on your phone. A list of list is basically a tree. But editing and operating a list of list is annoying, so it’s better to have a tool that has the concept of a node and a tree as a primitive.

Status: Archived by the owner in favor of work on a more cross-application tool: "I decided that having so many great features in a single editor is not the right way to write software, and I wanted to do something different outside of Neovim."

Verdict: Well-designed and impressive tool whose only major flaw is having been abandoned. Neorg should be able to do everything that

quarto-nvim

→ Quarto

Quarto Neovim Docs

WIP

Neorg Notes