SimpleZettel Documentation

SimpleZettel is a command line tool for managing a personal knowledge base (a zettelkasten). You can create boxes, add Markdown notes to boxes, and import files into boxes to keep track of other information such as scholarly articles. The user is also encouraged to consider nb, which was a huge inspiration for this project, and which the author still uses daily. SimpleZettel was created specifically to handle note numbering, which determines the order that they should be printed in. The following short video demonstrates the main features:

SimpleZettel was designed with the idea that with a little help from the user, notes should be easy to find later. It is the user's responsibility to name their notes and enter an appropriate header which indicates what the note is about. Once a note has been created, this tool will assist the user in finding it later by sorting notes according to the following scheme:

There are three types of note names:

Numeric: any note name matching the regular expression ^[0-9]+(\.[0-9]+)*$. For example 1, 1.23.2, or 32.2.11.9.4.
Alphanumeric: any sequence of valid UTF-8 characters not falling into the numeric category.
Invalid names: a sequence of characters which cannot be represented as a UTF-8 string.

Numeric notes come before alphanumeric notes, which come before notes with invalid names. Numeric notes are ordered according to the digits that appear before each period. For example: 1.1 < 1.2 < 1.2.1 < 1.3 < 2.1 < 2.1.1 < 2.2
Alphanumeric notes are sorted in alphabetical order.
Notes with invalid names are displayed in a random order.

With the above ordering in mind, it is recommended to name notes in such a way that notes have a clear hierarchy (i.e. the note whose name is 1.3.4.2 is related to note 1.3.4, but does not follow the same line of thought as note 1.3.4.1).

SimpleZettel will further assist you in finding information in your zettelkasten by printing out the first header of each note alongside its name. For example, if note 1.1 has the following contents:

SimpleZettel will list this note as 1.1 Options in Rust

As a more complete example, here is what the output of szettel might look like for someone who has been taking notes on the Rust programming language.

Naturally, over time many notes will be accumulated. SimpleZettel allows for listing files whose names match a regular expression; together with a little help from the user (naming their notes in a way that makes sense to the user), this is a powerful feature for filtering and finding notes. For example, taking the same Rust zettelkasten from above, the user can easily see all notes with 'depth' 2 by running the following:

So long as the user has chosen good names for their notes, and have entered short, useful headers, information will be easy to retrieve from the zettelkasten.

As a side note, the numbering scheme above was chosen because it makes the most sense to the author of this program. However, the author recognizes that this might not be best for everyone, and plans on one day allowing the user to specify a custom separator (inplace of the '.' used above) in their config file, and for allowing note names such as 1.1a. For now though, note names should fall into one of the two valid categories laid out above.

Installation

It is recommended to install using Cargo. However, binaries for Linux are provided in the releases page.

Options

-b

Specifies a box to use. If this option is not passed to szettel, it will use the currently selected box. This can be useful to view the contents of a box other than the current one, without having to switch boxes. For example, to display note 1.2 in box notes (while notes is not the current box), run szettel -b notes show 1.2.

-h

Display all options and subcommands for szettel.

Subcommands

For all commands which operate on notes, the default behavior is to operate on notes from the currently selected box. You can change this with the -b option as descriped above.

box

Perform operations on boxes. This subcommand itself has several subcommands:

List all boxes. This is the default subcommand, so szettel box and szettel box ls produce the same output. However, passing the -a flag to this command lists all boxes, even boxes which are not tracked (removed).

add

Add a new box. This creates the boxes directory under the directory ~/.szettel, initializes git for this directory, and places a .track file inside the box. This subcommand requires the name of the box to add, for example, szettel box add notes.

Remove a box. This does not remove any files (other than the .track file, which simply tells szettel that the box is tracked). It is up to you to decide if you want to actually delete your notes.

track

Tracks a previously deleted box. For example, if the user previously removed the test box (or has copied this directory of markdown notes from another location), they can tell SimpleZettel that it is a box to be tracked by running szettel box track test.

help

Display the help for this subcommand.

use

Selects the given box as the current box. This will also print out a list of all tracked boxes, with an indicator pointing to the current box.

add

Add markdown notes to a box. You must specify the note name when calling this subcommand, for example, szettel add 1.23.2. SimpleZettel will then drop the user into vim to edit the note. Once the user exits the editor, the user is asked if they would like to commit the change to git. If the user specifies that they would, they are once again dropped into an editor to specify the commit message. Currently vim is the only editor supported. This will change in the future.

List notes which belong to the current box.

show

Display a note. If no valid config file is found, only Markdown notes will be displayed, and they will simply be printed out to standard output.

edit

Edit a note. Just like the szettel add command, the user is dropped into vim to edit the notes contents. If the file is changed in any way, the user is prompted to commit the changes to git.

Remove a note from a box. Unlike the szettel box rm command, this command does remove the note file from the filesystem. Use carefully.

import

Copy a file into the current box. This is not limited to Markdown files, but can be any file. Note that SimpleZettel currently only supports listing Markdown and PDF files.

config

Check the config file for errors. Currently, this only tells the user if there are errors present, not where or what they are. Nice, huh?

help

Display all subcommands and options for szettel.

Configuration

The configuration of szettel is still very limited, but will expanded in the future. The config file should be located at ~/.szettel/config.toml, and should contain a single TOML table: the show table. The valid keys for this table are shown below.

show

The valid keys for the show table are as follows.

Defines the command to run when displaying a Markdown note. For example, the author prefers the value of this key to be glow. This currently only supports a command with out any arguments. This will be changed in the future.

pdf

Defines the command to run when displaying a PDF file. For example, the author prefers the value of this key to be sioyek. This currently only supports a command with out any arguments. This will be changed in the future.