Skip to main content

A command line tool implementing Luhmann's system of a "Zettelkasten".

Project description


Zettels is a command line tool implementing Niklas Luhmann's system of a

It's still in alpha stage and probably very buggy.

What does Zettels do?

Zettels is a command line tool to index markdown files (your zettels).
It reads YAML-metadata blocks as defined by
`pandoc <>`__
and also parses the `markdown
hyperlinks <>`__
in each file.

The resulting index contains the metadata and the targets of the

Have a look at the files in ``examples/Zettelkasten`` and
``examples/index.yaml`` to get a better idea.

Zettels can also be used to query the index. The output can then be
piped to other tools (like grep or as arguments for the text editor of
your choice).

It's intended to be used for a "Zettelkasten" like Niklas Luhmann used

What the heck is a Zettelkasten?

"Zettel" is German for "note" or "slip of paper". "Kasten" is German for
"box". Think of old style library catalogues.

Obviously, this piece of software is not a box of paper sheets. However,
`Niklas Luhmann <>`__ used
such a box in a very specific way for his academic work.

A wonderful introduction in Luhmann's system of a Zettelkasten are the
slides of a talk by Daniel Lüdecke: `Introduction to Luhmann's
Zettelkasten-Thinking <>`__

In Luhmann's own words: `Communicating with Slip
Boxes <>`__
(translation of "Kommunikation mit Zettelkästen").

If you speak German, there's more:

- Luhmann, Niklas (1981): Kommunikation mit Zettelkästen. Ein
Erfahrungsbericht. in: H. Baier / H.M. Kepplinger / K. Reumann
(Eds.), Öffentliche Meinung und sozialer Wandel. Opladen:
Westdeutscher Verlag. pp. 22-28
- Daniel Lüdecke: `Luhmanns Arbeitsweise im elektronischen
Zettelkasten <>`__
- Thomas Schlesinger: `Wissen konservieren und kuratieren mit dem
Zettelkasten nach Niklas
Luhmann <>`__
- Universität Bielefeld: Video - `Einblicke in das System der Zettel -
Geheimnis um Niklas Luhmanns
Zettelkasten <>`__

What, no GUI?

True. A GUI for querying the index would be nice. However, as such,
Zettels doesn't provide one. It is intended to be used in a toolchain of

I myself edit my Zettelkasten in my favourite text editor and have
created a little module that allows me to query its index from there.
So, if you use Textadept or don't care which text editor you use, have a
look at `ta-zettels <>`__.


If you're looking for a GUI, all-in-one approach to implementing
Luhmann's idea into software, I can recommend Daniel Lüdecke's
`Zettelkasten <>`__

Installation and setup

1. Install using pip (or pip3, depending on your OS):
``pip install zettels``
2. Run ``zettels --setup`` – follow the interactive setup process
3. Run ``zettels -su`` once to initially build the index.


Run ``zettels -h`` for a complete list of options. Some examples:

Build or update the index:


zettels -su

Shorthand for ``--silentupdate``

Querying the index

Show a list of all zettels:



Show a list of all zettels, but update the index first:


zettels -u

Show info about a specific zettel, e.g.



Show info about two zettels, e.g. and



Show a list of followups of a specific zettel, e.g.


zettels -f

Show a list of zettels a specific zettel links to, e.g.


zettels -l

Show a list of zettels linking to a specific zettel, e.g.


zettels -i

And finally, a bit of fun with pipes: Let's say you want to see which
zettels apart from itself link to the followups of


zettels -f | zettels -i | grep -v

Try it with example data

Run e.g.


zettels -s examples/zettels.cfg.yaml examples/Zettelkasten/

Zettel format

Zettels doesn't require your markdown files to have a metadata block.
But to be really effective parts of your Zettelkasten, a YAML metadata
block containing an entry for ``title``, ``tags`` and ``followups`` is

.. code:: yaml

title: 'Example Zettel'
tags: [example, question]
followups: [, subdir/, ../]

If no such metadata is present, Zettels will replace it with appropriate
"empty" values in the index:

- ``title``: "untitled"
- ``tags``: "[]"
- ``followups``: "[]"

Instead of finishing the metadata block with ``...`` you can also use

.. code:: yaml

title: 'Example Zettel'
tags: [example, question]
followups: [, subdir/, ../]

In fact, a zettel file may contain several YAML-blocks. However, Zettels
will only parse the first one. The metadata block may contain a variety
of other entries (e.g. ``author``, ``date``) – maybe for other tools,
like pandoc – but those other entries are ignored by Zettels and do not
become part of Zettels' index.

To manually link between zettels, use the "inline syntax" for markdown

.. code:: [.markdown]

[link text](url)

Links between zettel files should be relative links. The same is true
for entries in ``followups``.

Output format

The output can be tweaked to your needs. In the settings file (default:
~/.config/zettels.cfg.yaml), you'll find two settings:

- ``outputformat`` - standard format
- ``prettyformat`` - used when Zettels is called with the ``--pretty``

These output formats are given as `Python Format
Strings <>`__.
Query output consists of two fields that these format strings can


1. title - accessible by `'{0[0]}'`
2. path (relative to the Zettelkasten directory) - accessible by `'{0[1]}'`

By default the formats are:


outputformat: '{0[1]}'
prettyformat: '{0[0]:<40}| {0[1]}'

Standard ``outputformat`` just outputs the path(s) of the query results,
``prettyformat`` is a pseudo-table with the title(s) of the query result
in the first column (which is at least 40 characters wide), and the
path(s) in the second column.

The output format can also be tweaked on a per call basis with the
``-o`` flag, that takes a custom output format.

See the `Python Format String
Syntax <>`__
for details.


- Python 3.x
- `grep <>`__ &
`find <>`__– Your Python
runtime must be able to find and execute the UNIX tools ``grep`` and
``find``. Zettels is tested against GNU grep and GNU find, but other
implementations should be fine, too.
- `PyYaml <>`__
- `pathspec <>`__>=0.5.0

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
zettels-0.6.0-py3-none-any.whl (28.3 kB) Copy SHA256 hash SHA256 Wheel py3
zettels-0.6.0.tar.gz (34.7 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page