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 :doc:`extending` 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:

1. 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``.
2. 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 :ref:`using-md` (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 :ref:`using-md` for the
default implementation and in :doc:`extending` 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 :doc:`cli`.

.. _using-md:

Using the default Markdown implementation
-----------------------------------------

As a concrete example of the above, let us show how to use the default Markdown
implementation defined at :py:class:`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 :doc:`extending`.