1 unstable release

0.1.0 Nov 19, 2021

#6 in #note-taking

MIT license

20KB
515 lines

Zettl

⚡️A blazing fast way of maintaining powerful notes with connections between them.

asciicast

(i know its broken im too lazy to re-record)

Installing Zettl

To install Zettl, you will need the Rust toolchain installed. You can install Rust using rustup. Once you have Rust installed, you can either install zettl from crates.io.

$ cargo install zettl

Using Home Manager

Zettl now ships as a Nix flake with a home-manger module. Since zettl is not part of Nixpkgs (yet!), you need to add the zettl overlay to your nixpkgs.

If you use a flake to manager your NixOS configuration, you can add the following to your flake.nix

  inputs = {
   zettl.url = "github:hedonhermdev/zettl";
  };

  ...
  pkgs = import nixpkgs {
    inherit system;
    config = {
      allowUnfree = true;
    };

    overlays = [
      zetl.overlays.default
    ];
  };

And to add it to your home programs, you can do something like:

programs.zettl = {
  enable = true;
  settings = {
    zettl = {
      zettlDir = "${config.home.homeDirectory}/kasten";
      editorCmd = "${pkgs.nvimPacked}/bin/nvim";
      author = "Tirth Jain";
      name = "zettelkasten";
    };
  };
};

Initializing Zettl

You will need to create a directory to store your notes. You can tell zettl to use this directory by setting the $ZETTL_DIRECTORY variable. Note that zettl will use this directory for all operations so you will probably have to set this variable in your .bashrc (or your .zshrc).

$ mkdir ~/kasten
$ echo "export ZETTL_DIRECTORY=~/kasten" >> .bashrc

Initializing zettl creates a .zettl directory in your base directory.

$ zettl init

Configuring Zettl

You can change config options by setting values in the config file.

$ vim $ZETTL_DIRECTORY/.zettl/config.yml

Currently, zettl supports the following options:

---
name: My Zettelkasten
author: Me
editor_cmd: vim
editor_args: []
indexes: true
graph: true

An example, customised config will look like this:

---
name: My Zettelkasten
author: Tirth Jain
editor_cmd: nvim
editor_args:
  - "+Goyo"
  - "+Limelight"
indexes: true
graph: true

Using Zettl

Once Zettl is initialized, you can use it to write notes from anywhere.

# Create a new fleeting note. These are like daily notes.
$ zettl fleet
# Create a new note. This will be created in notes/some-idea.md. 
$ zettl note some-idea
# Create a new note in a category. This will be created in notes/project1/some-idea.md.
$ zettl note project1/some-idea
# Listing all notes.
$ zettl list
# Listing all fleeting notes.
$ zettl list -f

These commands will open a markdown file in the editor you specified.

Graphs and Indexes

Zettl creates _index.md files in each directory to index your notes. You can turn this off by setting the following in the config directory.

indexes: false

The fleets/_index.md file will look kind of like this:

---
title: Fleets Index
author: Tirth Jain
created: "2021-04-29 11:16:25"
---

# Fleets Index

- [[fleets/2021-04-28]]
- [[fleets/2021-04-29]]

Similarly, Zettl creates a .graph.json file to track connections between your notes. You can visualize this graph with a visualizer of your choice. I prefer 3d-force-graph. Note that connections are made using the [[mediawiki]] link format.

To turn off this graph generation:

graph: false

To manually create the graph and the indexes, you can run:

$ zettl graph
$ zettl index

How Your Notes are Saved

Zettl saves your notes as markdown files. After a few days of using zettl, your zettl directory will look something like this:

/Users/hedonhermdev/kasten
├── _index.md
├── fleets
│   ├── 2021-04-28.md
│   ├── 2021-04-29.md
│   └── _index.md
└── notes
    ├── SDNs
    │   ├── _index.md
    │   └── p4-notes.md
    ├── _index.md
    ├── devops
    │   ├── _index.md
    │   ├── git-server-setup.md
    │   └── homegrown-autodeployment.md
    ├── git
    │   ├── _index.md
    │   ├── cli.md
    │   ├── error-handling.md
    │   ├── git-in-rust.md
    │   ├── implementation.md
    │   └── internal-objects.md
    ├── how-to-zettel.md
    ├── vim
    │   ├── _index.md
    │   ├── autocmds.md
    │   └── vimrc-for-servers.md
    ├── workflow.md
    ├── zettl
    │   ├── _index.md
    │   ├── philosophy.md
    │   └── roadmap.md

Integrations

While zettl doesnt have a programmatic way to support integrations (yet!) but here are some integrations I can think of:

  • Version control with git
$ cd $ZETTL_DIRECTORY
$ git init
$ git add .
$ git commit -m "Saving notes"
  • Publish your notes as a static site with Hugo. This theme handles mediawiki links as well.
$ ln -s $ZETTL_DIRECTORY path/to/hugo/content
$ hugo serve
  • Fuzzy finding notes with fzf
# for notes
$ zettl note $(zettl list | fzf)

Dependencies

~12–24MB
~320K SLoC