-
-
Notifications
You must be signed in to change notification settings - Fork 139
Getting Started
Org-mode is a flexible note-taking system that was originally created for Emacs. It has gained wide-spread acclaim (this file itself is an Org-mode file, which is supported by GitHub wikis) and was eventually ported to Neovim.
To get the hang of it, we will create an org file in which we will keep all the repositories we want to check out in the future. First, let’s create an empty file called `repos.org`.
Org files often start with meta-information for the title and the author:
#+title: Repositories #+author: <Your Name>
These directives are not necessary but may give others (including you in the future!) a gist what this file is about. There are many more directives detailed at [TODO: add this to the docs]
To create a list of repositories, we start a new line with a dash, followed by the repo name we’d like to remember:
- Org Bullets
Congratulations, you created your first list! 🎉 From here, you can easily add new list items by pressing `<Leader><Enter>`, the so-called org `meta return`. It has different effects, depending on the current position of the cursor. If it’s on a list item, it will add another one. We will discuss other uses later on. [TODO: actually do that]
- Org Bullets - vim-table-mode
Our list is already functional, but it’s only scratching the surface of what Org-mode can do. Let’s look at how org files are structured using `headings`.
Any line starting with one or more asterisks (*) but without any preceding whitespace is a heading (also called headline). Let’s change our list items to 1st-level headings by replacing the dashes with asterisks:
* Org Bullets * Vim table-mode
The number of asterisks denotes the level of the heading: the more asterisks, the deeper the level. That is how we achieve nested structures in our org files.
* Org Bullets ** Synopsis * Vim table-mode
The content within a heading can be free form text, include links, be a list, or any combination thereof. Let’s add a short description:
* Org Bullets ** Synopsis This plugin is a clone of org-bullets. It replaces the asterisks in org syntax with unicode characters. * Vim table-mode
The full syntax for a headline is
STARS KEYWORD PRIORITY TITLE TAGS * TODO [#A] foo :bar:baz:
-
KEYWORD
, if present, turns the heading into a TODO item. By default this can beTODO
orDONE
(see the Customization section to change this). -
PRIORITY
sets a priority level to be used in the Agenda. -
TITLE
is the main body of the heading. -
TAGS
is a colon surrounded and delimited list of tags used in searching in the Agenda.
Headings (usually with a KEYWORD
) can also have deadlines, and/or be
scheduled with timestamps (e.g. <2022-12-31>) [TODO: explain the difference
between deadlines and scheduled headings]. Thus we could enhance our list
of repos like so:
* org-bullets.nvim :org: ** Synopsis This plugin is a clone of org-bullets. It replaces the asterisks in org syntax with unicode characters. * vim-table-mode :org: ** TODO Synopsis SCHEDULED: <YYYY-MM-DD> * plenary :lua: ** TODO [#A] Synopsis DEADLINE: <YYYY-MM-DD>
One final aspect of the org file syntax are links.
Links are of the form [[link][description]]
, where link can be a
- URL (http://, https://)
- path to a file (file:/path/to/org/file)
- target (any text surrounded by << and >>). If the target is in a different file the format is ‘file:~/path/to/org/file.org::My Target’
- headline within the same file
- headline with a custom id (#your-custom-id)
In order to easily go to the repositories we found online, let’s link to their actual website:
* [[https://github.com/akinsho/org-bullets.nvim][org-bullets.nvim]] :org: ** Synopsis This plugin is a clone of org-bullets. It replaces the asterisks in org syntax with unicode characters. * [[https://github.com/dhruvasagar/vim-table-mode][vim-table-mode]] :org: ** TODO Synopsis SCHEDULED: <YYYY-MM-DD> * [[https://github.com/nvim-lua/plenary.nvim][plenary]] :lua: ** TODO [#A] Synopsis DEADLINE: <YYYY-MM-DD>
A first customization of orgmode would look like:
-- init.lua
local org = require('orgmode')
org.setup_ts_grammar()
org.setup({
org_agenda_files = {'~/path/to/agenda/file/*.org'},
org_default_notes_file = '~/path/to/default/capture/file.org',
})
with all customization options going in the org.setup({})
.
All available options are detailed here, including setting new keybindings.
The org agenda is used to get an overview of all your different org files. Pressing `<Leader>oa` gives you an overview of the various specialized views into the agenda that are available. From each view you can press `g?` to see all the available key mappings. The most important ones are:
- t => change the TODO state of a heading
- <Enter> => open heading in current (agenda-)window
- <TAB> => open heading in another window
To quickly save thoughts, ideas or other things that come up regularly in your day without interrupting your current task, Org-mode offers you so-called captures. They can conveniently opened in any Vim buffer with `<Leader>oc`. Here we are presented with a list of availabe capture templates.
To aid us in our endeavour of saving interesting repos, let’s create a custom capture that saves us from manually adding them to the `repos.org` file. We add the following in our call to `org.setup()`:
org_capture_templates = {
r = {
description = "Repo",
template = "* [[%x][%(return string.match('%x', '([^/]+)$'))]]%?",
target = "~/org/repos.org",
}
}
After restarting Vim you should be able to select the `Repo` capture-template with `r` when you initiate a capture. If you have the link to the repo in you clipboard, it will be inserted into the link correctly. See the docs about the possible ways to configure your templates.
When we no longer need certain parts of our org files, they can be archived. Let’s say we are done with checking out the org-bullets repo, so we archive it by pressing `<Leader>o$` while on the heading. This will also archive any child headings. The default location for archived headings is <name-of-current-org-file>.org_archive, which can be changed with the org_archive_location option.
In case you want to preview, you can export your .org file to e.g., html with pandoc, see the docs.
Our Docs can be found here
Org-mode is has many more features than the tiny subset outlined here. Have a look around the official manual if you are interested in any particular topic. But please keep in mind, that this is a work-in-progress port for Neovim and not the original source for Emacs Org-mode. If you find any features you would like to see here, feel free to open an issue or (even better) get your hands dirty and create a pull request 😉