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:
^[0-9]+(\.[0-9]+)*$. For example 1, 1.23.2, or 32.2.11.9.4.1.1 < 1.2 <
1.2.1 < 1.3 < 2.1 < 2.1.1 < 2.2
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
szk 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:
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 (in place 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.
It is recommended to install using Cargo. However, binaries for Linux are provided in the releases page.
Specifies a box to use. If this option is not passed to
szk, 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 szk -b notes show 1.2.
Display all options and subcommands for szk.
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 described above.
Perform operations on boxes. This subcommand itself has several subcommands:
List all boxes. This is the default subcommand, so
szk box and szk 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 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,
szk box add notes.
Remove a box. This does not remove any
files (other than the .track file, which
simply tells szk that the box is tracked). It is up to you to decide if
you want to actually delete your notes.
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
szk box track test.
Display the help for this subcommand.
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 markdown notes to a box. You must specify the
note name when calling this subcommand, for example,
szk add 1.23.2. SimpleZettel will then drop the user
into the editor specified in the config file (defaults to
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.
List notes which belong to the current box.
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 a note.
Remove a note from a box. Unlike the szk box rm
command, this command does remove the note file from the
file system, and currently does not ask for confirmation. Use carefully
(and commit to git often).
Rename a note. Requires the name of the note to be moved, as well as
the new name. It is recommended that no file extensions be specified
on either argument. For example, to rename note
testing-one to
one, use
szk mv testing-one one. This will fail if
a note exists with the specified new name.
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.
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?
Search for a string among all the cards in the current box.
Display all subcommands and options for szk.
The configuration of szk is still very limited, but will expanded in the
future. The config file should be located at
~/.szettel/config.toml. The valid tables and keys
are shown below.
The valid keys for the general table are as
follows.
Defines the command to run editing any card, or adding a new card. This command will be run with the card's path as its argument.
The color to use for card names and the indicator of the current box.
This must be a valid Ansi 256 color code as a
u8. For example, the default value is
4.
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.
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.
Prefixes are used to indicate the filetype of each card, if the
filetypes feature is enabled during
compilation. It is recommended that each of the following have the same
number of characters (otherwise columns may not align properly).
The string to be shown before a Markdown card name.
The string to be shown before a PDF card name.