Quickstart

How `xettel` works

xettel is a Zettelkasten management software. It uses the folder/file metaphor to represents Zettelkästen and Zettels, that is, your Zettelkasten will be a folder, and your Zettels will be the files in this folder. Beyond that, xettel tries to be as agnostic as possible concerning your Zettels. Even though there is a default implementation for Zettels in Markdown, you may store your Zettels in any format you like, provided you can supply a way to extract the data. See Extending xettel for more information.

However, in order to perform some graph-related checks on your Zettelkasten and in order to find your files, filenames must abide by a few rules:

Filenames of Zettels must be of the form UID-name.ext where UID is either a 12-digit long number in base 10 or a 8-digit long number in base 36 (case doesn’t matter), ext must be the extension defined in your class, i.e., for Markdown files using the default implementation, it must be md, and name has no special constraints. By default, xettels creates Zettels with an uppercase number in base 36 for the UIDs based on the time they were generated. In base 10, this uid is just YYMMDDHHmmSS.
In order to perform graph checks and to plot the graph of the Zettelkasten, xettel assumes that your index file (i.e. the main entry point of your Zettelkasten) has the UID 0 (thus, in base 36, a filename for the index file may be 00000000-index.md).

Warning

Pay attention to the fact that UIDs are stored solely in the filename. You may not have two Zettels whose filenames begin with the same number, even if one is in base 36 and the other in base 10.

In order to keep the graph tidy (as much as it is possible) when plotting it, there is an extra rule concerning this time the content of your Zettels. If your implementation has tags (as has the default markdown implementation), you may have some Zettels that work has entry points to some subjects. For instance, you may have a Zettel uid-norway.md that has links to Zettels pertaining to Norway. Such Zettels are called hubs and should be tagged with hub. This will set them a bit further from the other zettels when plotting, especially when the link is between two hubs.

As said above, xettel is quite agnostic as to how you store your Zettels, however, when using the default Markdown implementation or one of its subclasses, please refer to the section Using the default Markdown implementation (cf. infra) for usage.

Because viewing your notes in the source format is not always pleasant, xettel allows you to export them in a given format. However, this is implementation dependant, and therefore is explained in Using the default Markdown implementation for the default implementation and in Extending xettel in full generality.

Setting up `xettel`

As explained above, in order to use xettel, you must first chose a folder to store your Zettels in, an implementation, and you must also define a template to create new Zettels with xettel new.

The config folder is by default at ~/.config/xettel. All of the config data is expected to be in the TOML file config.toml in this folder. For instance, here’s a default config.toml file.:

[Zettelkasten]
directory="/path/to/zettelkasten/folder"
template="/path/to/template/folder/template.ext"
zk_impl = "markdown"

This config file may contain additional fields for use with the implementations.

Todo

Set up a way to pick the config folder respecting XDG stuff.

Don’t forget to create a Zettel with uid 00000000 and you should be able to use xettel. Further usage is described in Command-line usage.

Using the default Markdown implementation

As a concrete example of the above, let us show how to use the default Markdown implementation defined at xettel.impl.markdown.ZettelMD.ZettelMD.

Files that are meant to be used with this class are standard Markdown files with YAML headers. Their expected extension is .md. For instance, here is a template:

---
title: Title
tags: [tag1, tag2]
abstract: abstract
---

CONTENT

Warning

The YAML header must be valid, empty fields, for instance, cause bugs.

YAML fields may be anything, the current implementation only parses the fields title, tags and abstract, but future implementations may use additional fields as well as classes derived from it.

Links in this format must verify the regex (?<=\[#)([0-9]{12}|[0-9a-zA-Z]{8})(?=\]), i.e. they must be of the form [#UID] where UID is either an 8-digit long number in base 36 or a 12-digit long number in base 10.

Exporting

This class levies pandoc to export Zettels to HTML. In order to do so, a new folder in created within the Zettelkasten folder called export. xettel calls pandoc with a number of metadata set for use with a template, however, it does not tell pandoc where to find templates or anything, making it unusable. To make it usable, you should create you own class, see Extending xettel.