srid/neuron

Future-proof note-taking and publishing based on Zettelkasten (superseded by Emanote: https://github.com/srid/emanote)

neuron

neuron is a future-proof app for managing your plain-text notes in Zettelkasten style, as well as for publishing them on the web. Read its philosophy.

Checkout Emanote, neuron's successor!

Neuron is being superceded by Emanote: https://github.com/srid/emanote

Highlights

• Work with a directory of markdown files
• Powerful linking syntax and hierarchical tagging
• Auto-generated static web site (see examples)
• Simple to use, with optional editor integration (emacs, vim, vscode, etc.)

Getting started

See https://neuron.zettel.page/install to install and use neuron locally. Or start from neuron-template if you just want to publish a neuron site using GitHub Pages.

Developing

Development documentation, including instructions to install from source, is available in CONTRIBUTING.md.

Discussions

To discuss and propose ideas, visit the Discussions tab on GitHub. To chat about the project join Matrix.

neuron's Issues

More convenient links

Linking between zettels is arguably one of the main features of the method, yet the syntax is quite clunky: [20200101](z://) (especially when typing on a phone). Would it be possible to make this more convenient ? For example, having just [20200101] seems quite markdown-y, since markdown supports link reference definitions.

Configurable theme colors

Allow some basic customization of the CSS (via neuron.dhall) so that not all Zettelkastens appear with teal as the primary color.

Might as well normalize heading colors as part of this work.

Query: nearby zettels

Add to query the functionality to retrieve nearby zettels

• zquery://search?linkFrom=<zid>
• zquery://search?linkTo=<zid>
• zquery://search?forestFrom=<zid>
• zquery://search?forestTo=<zid>

The "connections" pane should probably switch to using the last two.

Set up neuron in home-manager possible ?

I am convinced by the Zettelkasten method and wanted to integrate in my setup.

I am pretty much new to nix and as I saw you are using nix for continuous integration wanted to ask for help integrating neuron to my configuration.
This is what I have so far, is home-manager-based but should be not that different to regular nix:

{ config, pkgs, ... }:
with import <nixpkgs> {};
with builtins;
with lib;let
neuron = stdenv.mkDerivation {
   name = "neuron";
   src = fetchFromGitHub {
	 owner = "srid";
	 repo = "neuron";
	 rev = "dd900dd249742aabfb1dba89f498b6afdb7f4531";
	 sha256 = "1zcgd46hjjhsj1g2sifx0hp1cvmd3nssn3nvw48vb5k40sfslkdq";
   };
   phases = [ "installPhase" ];
   buildInputs = [ makeWrapper ];
   installPhase = ''
	 mkdir -p $out/bin
	 makeWrapper $out/neuron $out/bin/neuron
   '';
};
in
{
  home.packages = with pkgs; [
    neuron
  ];
}

I am getting:

these derivations will be built:
/nix/store/flz6zqa1hjpjqmhgiba7z7l6jp0d1ygx-neuron.drv
/nix/store/rdqc7dzmm230w0bxcn7ylds756s6qjrq-home-manager-path.drv
/nix/store/2pww4m99hmh5bmjk0xlall9n91l7wd5m-activation-script.drv
/nix/store/idjl4rvj15s0fa2fcyi6hngzrdixmx4i-hm_fontconfigconf.d10hmfonts.conf.drv
/nix/store/s32pcgy9xp21x9pakhimlcxgr078m6hm-home-manager-files.drv
/nix/store/yhmxwcq4vihrkclr9v53qfcb7rnf6yi7-home-manager-generation.drv
building '/nix/store/flz6zqa1hjpjqmhgiba7z7l6jp0d1ygx-neuron.drv'...
installing

Builder called die: Cannot wrap '/nix/store/3ca7lxvvd50sgs4l6743fhx1a0fnyqf4-neuron/neuron' because it is not an executable file
Backtrace:
7 assertExecutable /nix/store/06nq4z17fh43wrbn6hl1yq7bzs99lpr1-hook/nix-support/setup-hook
39 makeWrapper /nix/store/06nq4z17fh43wrbn6hl1yq7bzs99lpr1-hook/nix-support/setup-hook
1326 genericBuild /nix/store/qghrkvk86f9llfkcr1bxsypqbw1a4qmw-stdenv-linux/setup
2 main /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25b-default-builder.sh

Add Structured Markup

For Google juice. To be generated based on the graph/tree.

• Sitemaps: cf. srid/zulip-archive#10
• Structured Markup: cf. srid/zulip-archive#11

Structured markup is more important sitemap. Sitemaps are only relevant for really large zettelkastens hosted publicly.

In particular breadcrumbs are relevant to zettelkastens: https://developers.google.com/search/docs/data-types/breadcrumb

---

• Structured data: breadcrumbs
• Structured data: article

configuration: switch from Dhall to something else?

We may have to do this to ensure backwards compatibility going forward.

Suppose the next version of neuron adds a newer field to the Dhall configuration. The new parser will not be able to parse older configuration in existing Zettelkastens, because Dhall requires all fields in a record to be present.

I'm not aware of any workaround, so Dhall seems unsuitable to the project.

Neuron's configuration is not complicated; it is just a list of key-value fields. Adding a new field must continue to support older configurations (which won't have this new field). Each key will have a default value (title being the only mandatory key), so if a field is missing neuron will use the default value.

TOML is one candidate; and I'm open to consider other formats. The main goal here is backwards compatibility beyond the public release (0.2).

Display tags in HTML interface

In the individual zettel pages.

Error when using queries and custom ids

I use a different ID scheme (with letters instead of numbers to encode the date) than the one neuron uses. So far I have had no problems, except when using zquery://. Specifically, this line:

neuron/src/Neuron/Zettelkasten/Link/View.hs

Line 35 in f7f0c13

let zettels = reverse $ sortOn zettelIDDate $ matchID <$> runQuery store q

tries to parse the zettel ids to sort them, but obviously that fails for me. Since sorting ids alphabetically should do the same as sorting them by date, would it be possible to not try to parse the ids here ?

Add unit tests

cf. #32 (comment)

Make root redirect to z-index.html

If the user has no index.md zettel, have the root of the site automatically redirect to z-index.html. Then, adjust the tutorial accordingly.

Public Zettelkasten sites tend to have an index.md (to render as the root of the site); but my private Zettelkasten has no such index. In fact, not having an index zettel is favourable in order to allow graph clustering (#18) to break up the graph sensibly.

Add to nixpkgs

OpenGraph support for zettels

https://ogp.me/

• Either add a description field, or use the few 300 letters or so from the body.
• Extract the first image to use as preview

Quick entry for neuron, a short tutorial

Currently I use st, i3’s floating windows, fzf, ripgrep and tmux to create a keybinding to popup open any zettel by title search. Write about this workflow in neuron.srid.ca.

Relevant commit

Add emacs mode to docs

https://github.com/felko/zettel-mode

Allow customizing favicon

Add faviconPath to neuron.dhall configuration, with the default using neuron's favicon. See #72 (comment)

Add "backlinks" section

The connections pane show a subset of backlinks (links using z:), but ignores other backlinks (those that use zcf:). It might be worth displaying all backlinks in a dedicated section, regardless of the link type used.

To do this, first revamp the graph connections to contain all link types (category tree would use only one link type).

Unable to install on WSL

$ nix run nixpkgs.nix-info -c nix-info -m
 - system: `"x86_64-linux"`
 - host os: `Linux 4.4.0-17134-Microsoft, Arch Linux, noversion`
 - multi-user?: `no`
 - sandbox: `no`
 - version: `nix-env (Nix) 2.2.1`
 - channels(me): `"nixpkgs-19.09pre191265.c4adeddb5f8"`
 - nixpkgs: `/home/me/.nix-defexpr/channels/nixpkgs`

 $ nix-env -if https://github.com/srid/neuron/tarball/master

gives

unpacking 'https://github.com/srid/neuron/tarball/master'...
unpacking 'https://github.com/srid/rib/archive/6ba865b4b9e4831cd484c868475004038d26fab8.tar.gz'...
unpacking 'https://github.com/nixos/nixpkgs/archive/24c765c744b.tar.gz'...
error: attribute 'name' missing, at /nix/store/cgfjk9d24dip7rk1kxpnyyv77h994wqz-source/lib/sources.nix:76:65

Cluster detection

As the Zettelkasten grows, notes will naturally belong to specific clusters. For eg., science-related notes would be part of one cluster, whereas personal journal-related notes would be in an entirely different cluster.

In computer science, we call this a connected component of a graph. Pictured below is a graph with three connected components.

Neuron's z-index should distinctly display these components. If there are three components, for example, there should be three separate trees/forests.

RSS support for zquery://

Support for generating RSS out of a zettel query.

Dangling zettles not displayed in the forest

Looks like after #30 was merged dangling zettles are not displayed in the forest (z-index).

But they should be displayed as top level, if I understood the docs write (Top-level zettels).

Adding one zettle to the guide:

It doesn't show in the forest.

Adding another one and linking:

Now that there's one link it shows.

http server is strictly not required

Document this:

Via zulip

Configuration

Add config.dhall in the notes directory, for specifying things like site title, URL, theme color.

Configuration should be optional, with sensible defaults.

• z-index.html should be index.html by default unless configured to point to elsewhere
  • Verify that ${zindexname}.md does not exist before writing its HTML
• Make mathjax include configurable

Generalize: configurable INDEX

Should not be hardcoded to "INDEX.md".

"Edit this Zettel on Github"

Add a link that will take users to the zettel on Github, allowing them to edit it.

Requires #15 (for editUrl configuration)

Add `-e` option to automatically open in editor

The following:

neuron ./notes new "Some title" -e 
neuron ./notes search -e

Should automatically open the file using $EDITOR.

Should be equivalent to piping to xargs -rt $EDITOR.

Tasks

• Add -e to the new command
• Add -e to the search command

Parsing fails on non-RFC3986 compliant urls

With the following zettel:

---
title: Title here
---

- [Some link](http://example.com/articles?include=author&fields[articles]=title)

I get this error:

[Rib] Unhandled exception when building <unknown>: Error when running Shake build system:
  at action, called at src/Development/Shake/Forward.hs:123:5 in shake-0.18.5-1boelLdAnakJTib1YXjM5c:Development.Shake.Forward
* Raised the exception:
user error (2013601.md:5:64:
  |
5 | - [Some link](http://example.com/articles?include=author&fields[articles]=title)
  |                                                                ^
unexpected '['
expecting '#', '%', '&', '+', '/', ':', '=', '?', '@', end of URI, sub-delimiter, or unreserved character

Looks like the parser for links can't handle [] inside URLs? https://jsonapi.org/examples/ shows more examples (for in unit tests)

Vim integration

Some ideas here: https://github.com/aleator/Zettel-hs

Generalize: remove notesDir hack

Hardcodes to "notes".

`neuron … search` misbehaves when there is only one note

To reproduce:

$ mkdir test
$ neuron test new Test
$ neuron test search

It will misbehave in a few ways:

• There will be a [bat error]: 'title': No such file o… error message
• Attempts to refine the query will generate 0 results
• Selecting the single note will return ./test/title instead of the path to the note

Once you add more than one note, though, the problem disappears

Enable queries from the CLI

Add a neuron ... query command to the CLI, which would ease editor support. It would return a list of Zettel IDs that match the specified query. Example: neuron ... query --tag=science

Maybe use this to find zettels by title or content with ripgrep, sort of like neuron ... search does but returning only the list of IDs instead of starting a fzf interface.

Standardize on zettel ID scheme

The general expectation so far is that the IDs are of a specific format, although the app is pretty lenient ("index.md" for example works).

Some users, like @Nadrieril from #60, use a different ID scheme.

One of the ideas in #59 is to support short and simple links like <2011502> (instead of the current [2011502](z:/)). Knowing what to expect ahead is necessary to properly parse links.

Should the next version of neuron:

• allow only numeric IDs like 2011502?
• allow custom alphanumeric IDs like 20dtbvs (cf)

I suppose a third option is to strongly recommend numeric IDs - but fail gracefully where users use alphanumeric IDs. For example, zquery's theme=withDate argument should render using the default theme, and render a warning in the HTML when the IDs are not date encoded numeric IDs. This inequality would have to be represented at the type level:

data ZettelID 
  = DateID Day -- Numeric
  | CustomID Text -- Alpha numeric

Disable mathjax via configuration

Leave it enabled by default (for backwards compat), but add a configuration field so that the following can be disabled:

• MMark extension
• JavaScript include

Specifying the notes dir with an absolute path causes InvalidRelDir error

Hi.

I started playing with Neuron a couple of days ago. When I updated to master today, I noticed that I could no longer specify the notes directory as an absolute path:

$ neuron /home/$USER/zettelkasten new "foo"
neuron: InvalidRelDir "/home/$USER/zettelkasten/"

Relative paths work fine:

$ cd $HOME
$ neuron zettelkasten new "foo"
zettelkasten/2012606.md

I assume this is unintended behavior, because it seems strange to only allow relative paths.

I ran git bisect, and commit 7b6c112 appears to be the one causing the problem. I don't know Haskell very well, but the changes to inputDir and directoryAside look related.

Thanks!

Tree view should be complete

If a zettel has multiple parents, that zettel sub-tree must appear on every one of them. Currently, dfsForest picks one parent, and ignores the rest.

Minimum neuron version

Requires #40

Allow user zettelkastens to specify the minimum neuron version they require to function correctly. Specify this version in the configuration file neuron.dhall. Example:

{ neuronVersionMinimum = "0.2"
, ...
}

Open questions:

• Should there be an upper bound as well? (neuronVersion = ">= 0.2 && < 0.3")

Hierarchical tags support

If a zettel has the following metadata

---
title: Some zettel
tags:
  - journal/work
---

Should querying for tag=journal include journal/work zettels as well? Or would this behaviour be specified explicitly by the user somehow?

How to install

Initially I was lazy and tried to just: nix-env -if https://github.com/srid/neuron/tarball/master but it doesn't bring neuron into your env, rather it brings sridca from the example and it's not immediately obvious how to modify things so that you get the functionality described in https://www.srid.ca/2010101.html

I thought this was a cli for interacting with the zettelkasten? I figured it'd be a bit like xmonad for notes?

Edit: cool project thanks for sharing!

Error on Ubuntu, after install according to README

Error on Ubuntu, after install according to README:
In the browser, http://127.0.0.1:8080/:

Directory listings disabled

and in the terminal:

$ neuron rib serve
T480:~/Downloads/neuron$ neuron ./guide rib serve
[Rib] Generating guide/ (full=True)
[Rib] Serving guide.output/ at http://127.0.0.1:8080
# guide/neuron.dhall
# guide/2011401.md
[Rib] Unhandled exception when building <unknown>: Error when running Shake build system:
  at action, called at src/Development/Shake/Forward.hs:123:5 in shake-0.18.5-HAvExuv9yqpGvWjbissEYC:Development.Shake.Forward
* Raised the exception:
guide/2011401.md: hGetContents: invalid argument (invalid byte sequence)

[Rib] Watching guide/ for changes

Any ideas? Many thanks!

Add --version CLI argument

It must also show the git revision.

`neuron query` is dumping logs during first run

This will break JSON parsing of the output

Re-evaluate srid/rib#140

Add a server mode that renders errors

Right now if there is an error while running neuron, the error is displayed on the terminal and the update doesn't show on the served pages. I would like an option that makes neuron display an error message on the served page instead. That way I can leave neuron running on a server and if a zettel fails to parse I will see it when I try to access the corresponding webpage.

Generalize: copy CSS style

Open-sourcing

I have been integrating neuron in my daily workflow, it is the best note-taking system I have used so far.

It would be great if this software is released under an open-source license.

Tarball install is broken

Serve request only to local machine

This is more a srid/rib issue, but it is critical to neuron.

Neuron should only serve requests from the machine it is hosted on by default, and not to everyone on the network.

This is important for machines with no firewall setup.

RSS feed support

Support for generating RSS (or Atom) feeds for a selected subset of zettels.

cf. ChrisPenner/slick-template#8

Tag-based proposal

Query to route mapping could perhaps be specified in the config file `neuron.dhall`.

{  atomFeeds :: [{ _1 = "z:zettels?tag=blog", _2 = "feed.xml"}]
, ...
}

---

• Initial implementation
• Test it in production
• Documentation

Known issues to fix:

• Zettel title should not be in feed item body
• Feed title should include not only zettel title, but also site title from neuron.dhall

Improvements:

• Add feed icon based on favicon

zquery: should display the query itself

The tag used to query, for example, should be displayed alongside the zettel list in neuron's web interface.

An URI flag should be used to control this behavior.

Create 'guide' repository

• Talk about zettelkasten
• Talk about neuron
  • zettel id
  • graph
  • link schemes
  • link query

All using neuron itself. And as a template repo for new users.

Add example Zettelkastens to README

• Add public Zettelkastens
  • https://www.srid.ca/
  • https://haskell.srid.ca/
  • ... yours?
• Document linkTheme=withDate (ref)

Zettel search in CLI

A command that searches zettels by title (or content) and outputs the filepath of the selected zettel. Use fzf and ripgrep (made available via static which) to implement.

CLI - neuron search. Direct edit CLI: vim $(neuron search).