neuron-mode is an Emacs major mode derived from markdown-mode to edit notes using the neuron Zettelkasten manager.
neuron-mode demo in doom emacs
-
Install neuron and make sure that the
neuroncommand is in your path. -
Install neuron-mode, either via MELPA (recommended) or manually by cloning this repository.
If you are using an emacs distribution like doom emacs or spacemacs, refer to this paragraph to see how neuron-mode can be integrated into your configuration.
All commands are executed in the active zettelkasten which is either detected by
traversing the directory hierarchy upwards until a neuron.dhall file is met
(see neuron configuration), or
otherwise it uses the zettelkasten that is specified by
neuron-default-zettelkasten-directory (a path). Although neuron.dhall files
are not mandatory to use neuron itself, this is what enables neuron-mode
automatically when opening a markdown file. neuron-mode will then cache the
zettels and regenerate it when needed (typically when creating a new zettel).
Sometimes, when the zettelkasten is modified externally to neuron-mode, you
might need to invalidate the cache and rebuild it manually, which is done with
the neuron-refresh command. This will also reload the titles displayed next to
zettel links (see next paragraph).
neuron-mode allows you to browse your zettelkasten directly from Emacs. Most importantly, neuron links are shown together with their titles so that you don't need to read the zettel from the associated HTML file anymore.
neuron links can also be followed using neuron-follow-thing-at-point. For
queries, it will prompt you to select a zettel that match the query under the
point.
Navigating "upwards" is also possible, using the neuron-edit-uplink function.
The neuron-edit-zettel will prompt you with the list of zettels, where you can
search by title, by tag or by ID using ivy.
projectile can also be useful as a complement to neuron-mode since it allows you to search the zettelkasten by content.
You can create new zettels from Emacs, neuron-mode will take care of creating the file with a generated hash in the current active zettelkasten.
Links can be inserted using neuron-insert-zettel-link which will prompt you to
select an existing zettel in the active zettelkasten. Zettels can also be linked
and created on the fly by using neuron-insert-new-zettel. A third way to
insert links, assuming that you use company, is by typing <a few keywords and
then running company-neuron. This will show all the zettels whose titles match
those keywords. You can enable company-neuron automatically by calling
company-neuron-setup which will trigger the autocompletion when you start
typing a link. You can enable this globally by adding a hook to neuron-mode:
(e.g. (add-hook 'neuron-mode-hook #'company-neuron-setup)).
To avoid typos in tags which might mess up the organization of your
zettelkasten, use neuron-add-tag/neuron-add-tags which will allow you to
select from already existing tags.
Rib commands can be executed from Emacs. Running neuron-rib-generate will
compile your zettelkasten to HTML. This can also be done automatically using
neuron-rib-watch which will generate every time you save a zettel.
The resulting HTML files can then be accessed either from neuron-mode with
neuron-open-current-zettel which will open the HTML that is associated with
the zettel being edited, or globally with neuron-open-zettel.
Alternatively, you can use the rib server to read your zettelkasten from your
browser. The server can be started using neuron-rib-serve and stopped using
neuron-rib-kill. Similar functions are provided to open the zettels in the web
app rather than local files (respectively neuron-rib-open-current-zettel and
neuron-rib-open-zettel).
| Command | Default binding | Description |
|---|---|---|
neuron-new-zettel |
C-c C-z |
Create a new zettel and open it for edition |
neuron-edit-zettel |
C-c C-e |
Select an existing zettel and open it for editing |
neuron-edit-uplink |
C-c C-, |
Select and edit a zettel that links to the current one |
neuron-add-tag |
C-c C-t |
Select and insert a tag in the current zettel's YAML metadata block |
neuron-add-tags |
C-c C-S-t |
Same as neuron-add-tag but adds multiple tags simultaneously |
neuron-query-tags |
N/A | Select a tag and then a zettel with that tag |
neuron-replace-tag |
N/A | Replace a tag by another across the entire zettelkasten |
neuron-open-current-zettel |
C-c C-r |
Open the current zettel's generated HTML file in the browser |
neuron-insert-zettel-link |
C-c C-l |
Search a zettel by content and insert the link at point |
neuron-insert-new-zettel |
C-c C-S-l |
Combine neuron-new-zettel and neuron-insert-zettel-link |
neuron-create-and-insert-zettel-link |
N/A | Like neuron-insert-zettel-link but can also create new zettels |
neuron-create-zettel-from-selected-title |
N/A | Transform the selected text into a new zettel |
neuron-insert-static-link |
C-c C-s |
Insert a link to a selected file in the static directory |
neuron-toggle-connection-type |
N/A | Toggle the connection type under point, between cf and folgezettel |
neuron-open-daily-notes |
C-c C-o |
Open today's notes if it exists, or create it otherwise |
neuron-refresh |
C-c C-S-r |
Regenerate the zettel cache and title overlays in all neuron-mode buffers |
neuron-toggle-id-visibility |
N/A | Toggle between showing the titles next to the IDs or over them |
neuron-follow-thing-at-point |
N/A | Override markdown-follow-thing-at-point to handle zettel URI protocol |
neuron-edit-zettelkasten-configuration |
N/A | Open the neuron.dhall file at the root of the current zettelkasten |
neuron-rib-generate |
N/A | Perform a one-off generation of the site |
neuron-rib-serve |
N/A | Start the wep application on localhost:8080 |
neuron-rib-open-z-index |
N/A | Open the web application at localhost:8080/z-index.html |
neuron-rib-open-zettel |
N/A | Select and open a zettel note in the web appliation |
neuron-rib-kill |
N/A | Kill the web application process |
company-neuron |
N/A | Trigger a company tooltip in which you can insert links by autocompleting by title |
neuron-default-zettelkasten-directory(default:"~/zettelkasten)
Defines the fallback zettelkasten when the current directory is not located in a zettelkasten.neuron-executable(default:neuron)
Path or wrapper around the neuron executable.
Example: this can be useful when using Emacs from Windows, while having neuron installed on WSL, in which case you can setneuron-executabletowsl neuron.neuron-generate-on-save(default:nil)
Generates the site when saving a note. Opens a compilation buffer (neuron-rib-generate)neuron-id-format(default:'hash)
Controls the default ID format used when creating new notes.
It can be set to:'hash: generates an unique 32 bit UUID (default behavior of neuron)'prompt: asks for the ID when creating a new zettel- a function: generate a custom ID based on the zettel title. (not recommended
for actual knowledge based zettelkastens but might be useful for e.g.
slugging the titles for documentations) The function has to generate a valid
neuron ID.
Example: If you want to have slug-converted title as ID, you can put the following in .emacs \(defun sluggify (title) (s-join "-" (split-string (s-downcase title)))) (setq neuron-id-format 'sluggify)
neuron-title-format(default:# %s)
Format string for title of a new zettel. This format string will be run throughformat(with title as argument) to populate the new zettel.neuron-default-tags(default:nil)
A list of tags to add to zettels when they are created. This does not affect daily notes.
Example:stub(to mimic Wikipedia's stubs)neuron-tag-specific-title-faces(default:nil)
An alist that associates tags to faces, which will appear in the title overlay when a link points to a zettel that has the corresponding tag. Example:'(("stub" hl-todo))neuron-daily-note-id-format(default:"%Y-%m-%d")
Format that controls the filenames of newly created daily notesneuron-daily-note-title-format(default:"%x")
The format of titles for new daily notesneuron-daily-note-tags(default:(list "journal/daily"))
The default tag of daily notes.neuron-rib-server-host(default:localhost) \neuron-rib-server-port(default:8080)
The host and port on which the rib server will runneuron-max-completion-width(default:30)
The maximum number of columns after which the company completion will truncate the titles to fit the given width.
neuron-make-title(default: capitalizes the first word)
A function that is called byneuron-create-zettel-from-selectionto transform the text into the actual title of the new zettel.neuron-show-ids(default:nil)
Whether to show the IDs next to zettel titles, rather than having the titles completely hide them. Can be toggled usingneuron-toggle-id-visibility.
doom-emacs users can use this configuration to work with neuron-mode:
https://gist.github.com/felko/cdb3fc19b3a60db27eb3c5bd319fc479
(include those files in .doom.d/modules/tools/neuron)
This creates a private module that can then be enabled by inserting neuron
under the :tools section of your doom! block (inside your init.el).
A spacemacs layer for neuron-mode along with installation instructions can be found in the LightAndLight/spacemacs-neuron repository.