[][src]Crate libzettels

Libzettels is a library intended as a backend for applications which implement Niklas Luhmann's system of a "Zettelkasten".

  • If you want to develop a Zettelkasten application, and want to know more about libzettel's approach, see the project's README.
  • If you (want to) develop a Zettelkasten application, and want to have a look at libzettel's API, continue reading here.
  • If you're looking for a Zettelkasten application, have a look at Zettels.
  • If you have no idea what a Zettelkasten is, have a look at Zettels' README, in particular the section "What the heck is a Zettelkasten?"

API Introduction for application developers

The heart of a Zettelkasten is the data representing the interrelations between the zettels. In libzettels, all that information is bundled in the Index. See its Fields
for details.

A YAML-representation of an example Index might look like this:

        title: File 1
        followups: [file2.md]
        keywords: [example, first]
        links: [subdir/file3.md]
        title: File 2
        followups: [subdir/file3.md]
        keywords: [example, second]
        links: []
        title: File 3
        followups: []
        keywords: [example, third]
        links: [file1.md]
    secs_since_epoch: 1543078763
    nanos_since_epoch: 449322318

But where does that data come from? From the user's files that make up the Zettelkasten. These files must contain the necessary information, which is represented by the struct Zettel.

Two typical use cases, three central structs

In essence, a user does two things with a Zettelkasten.

  1. Write zettels and by doing so generate data about the interrelations between them.
  2. Query the Zettelkasten and inspect the interrelations between the zettels.

Roughly speaking,

  1. the Zettel struct (or rather the logic it represents), is used for writing, while
  2. the Index is used for querying the Zettelkasten. And finally,
  3. the Config struct represents the users configuration. You can easily extend this struct for your application.

So, depending on what aspect of your application you're working on, one of these three is your place to start. But have a look at API Levels, first.

API Levels

libzettels discerns two API levels: Basic and Extended.

Which to choose

libzettels was designed with a certain kind of applications in mind: Applications, where users edit the YAML metadata of their zettels manually. (If you have no idea what I'm talking about, see the section "What does libzettels do?" in the project's README).

  • If your application lets users edit their zettel files manually, use the Basic API.
  • If you want to hide the zettel files away and give them some GUI forms, rich text editing or the like, you'll probably need a
    bit more granular control. That's what the Extended API is for.

Don't worry

For simplicity's sake, the API levels are not hard-coded, enforced or anything. They exist only in the documentation. Meaning: I have marked the functions that you probably won't need with "Extended API". But feel free to mix and match. I won't stop you.



Module to generate a set of example files.



Config represents the user's configuration. See "Fields" for details of what each value represents. It bundles user specified settings from a configuration file and can be serialized to and deserialized from such a file.


The heart of a Zettelkasten is the data representing the interrelations between the zettels. All that information is bundled in the Index. See its Fields
for details.


A struct containing relevant data about a Zettel.



All possible errors that can occur when constructing the index and parsing zettel files.


The Index is created not only by reading each zettel's YAML-metadata, but by scanning the document body of each zettel and parsing the markdown for links to other zettel files. The enum IndexingMethod defines the different methods that can be used to do this latter task.


User configuration that defines which zettels should be considered as the start of a sequence.