Tutorial

Make sure you have already installed neuron (see Installing). Then follow this tutorial to get your own Zettelkasten up and running.

Test with an existing Zettelkasten

The neuron git repo comes with a Zettelkasten of its own at the ./doc folder. Indeed, the very site you are viewing is generated by neuron from that Zettelkasten. Our goal in this section is to use neuron to generate this site locally, such as to give you a feel for how neuron works before using it to create your own Zettelkasten.

You will need to clone the git repository:

git clone https://github.com/srid/neuron.git
cd neuron

Now run the neuron Web interface on the ./doc Zettelkasten:

cd ./doc
neuron gen -wS  # Use 'neuron rib' if using neuron v1

It can be accessed at localhost:8080. It should match what you see at neuron.zettel.page.

Create your own Zettelkasten

There are a few ways to do this.

1. Copy the ./doc directory and work from there; or
2. Use the template repository in Automatic Publishing; or
3. Create one from scratch.

For this tutorial, we choose the last option.

Neuron expects the Zettelkasten directory to contain a neuron.dhall, as well as a list of Zettel Markdown notes. By default, the current working directory will be used as your Zettelkasten directory (which you can override using the -d option). Create this directory first, and add a basic neuron.dhall (see Configuration file):

mkdir ~/zettelkasten
cd ~/zettelkasten
touch neuron.dhall  # Empty file is accepted

Now create (see Creating and Editing zettels) your first zettel file:

neuron new -e

This will open your text editor¹ with the newly created file (neuron uses a random filename by default; let’s assume it is 6479cd5e.md) and its title already filled in. Enter some text, and exit the editor.

Next, create an “overview” zettel called index.md — it would be the welcoming page of our Zettelkasten web interface. This time we explicitly tell neuron the ID to use, instead of having it generate a random one:

neuron new -e index
# Note that you can also create this file manually, i.e.: 
#   echo "Hello" > index.md

In the text editor, link it (see Linking) to your first zettel. It should look like this:

# My Zettelkasten

From here, you can visit: [[6479cd5e]]

Your Zettelkasten directory should now contain two zettels–named 6479cd5e.md and index.md. Now it is time to run the neuron Web interface:

neuron gen -wS # Use 'neuron rib' if using neuron v1

• The -w option will watch your Zettelkasten directory and regenerate HTML files.
• The -S option runs a HTTP server serving the generated HTML files.
  • You can ignore it, and use neuron open instead.

Access it at localhost:8080 (or use neuron open). You should expect to see the contents of your overview zettel, which should link to the first zettel created. Clicking the tree icon in the nav bar should take you to the Graph visualization of your Zettelkasten.

Growing your Zettelkasten

Congratulations, you have created your first Zettelkasten using neuron! From this moment onwards, simply use the new command to create new zettels, search command to open existing zettels (or see Editor integration for editor support). As your Zettelkasten grows over time, more value will be derived from it.

What’s next?

Read Guide next to learn all the concepts and features in Neuron.