xettelkasten

A simple LaTeX-centric Zettelkasten written in Bash.

Introduction

xettelkasten (or xk for short) is a command-line tool designed to help you manage a Zettelkasten—a personal knowledge management system—using LaTeX documents. It streamlines the creation, organization, and interconnection of notes (zettels), making it easier to build a robust and scalable knowledge base.

Features

• Easy Zettel Management: Create, list, rename, and remove zettels with simple commands.
• References and Tags: Link zettels together using references and categorize them with tags.
• LaTeX Integration: Generate high-quality PDFs of your zettels using LaTeX templates.
• Git Integration: Keep your zettelkasten version-controlled with built-in Git commands.
• Extensibility: Customize and extend functionality with user scripts.
• Configurable: Customize paths, templates, and settings to fit your workflow.

---

Installation

Prerequisites

• Nix Package Manager (optional): For installation using Nix Flakes. No other dependencies needed then.
• Bash: xettelkasten is written in Bash and requires a Unix-like environment.
• LaTeX Distribution: A full LaTeX installation is needed for compiling zettels (e.g., TeX Live Full).
• Go (optional): Required if you plan to use Go-based user scripts.

Option 1: Install Using Nix Flakes

If you're using Nix with Flakes enabled:

1. Clone the Repository:

   git clone https://github.com/lentilus/xk.git
   cd xettelkasten

2. Build the Package:

   nix build

3. Install the Binary:

   nix profile install .#default

   This will install xk to your Nix profile.

Option 2: Manual Installation (not recommended)

1. Clone the Repository:

   git clone https://github.com/lentilus/xk.git
   cd xettelkasten

2. Install Dependencies:

   Ensure that at least bash, and some LaTeX distribution (e.g., texlive-full) are installed on your system.

3. Copy the Executable:

   sudo cp bin/xettelkasten /usr/local/bin/xk
   sudo chmod +x /usr/local/bin/xk

4. Copy the Libraries and Configuration Files:

   sudo mkdir -p /usr/local/lib/xk
   sudo cp -r lib/* /usr/local/lib/xk
   sudo mkdir -p /usr/local/etc/xk
   sudo cp -r etc/* /usr/local/etc/xk

---

Quick Start Guide

Step 1: Initialize Your Zettelkasten

Initialize a new zettelkasten in the default location:

xk init

This creates a new zettelkasten directory with necessary templates and configuration.

Step 2: Create a New Zettel

Create a new zettel (note):

xk insert -z "My First Zettel"

This will generate a zettel with the name My_First_Zettel.

Step 3: Edit Your Zettel

Open the zettel in your preferred text editor:

nano "$(xk path -z "My First Zettel")/zettel.tex"

Add your content between the \begin{document} and \end{document} tags.

Step 4: Compile Your Zettel to PDF

Navigate to your zettel directory and compile using LaTeX:

cd "$(xk path -z "My First Zettel")"
pdflatex zettel.tex

This will generate a zettel.pdf file in the same directory.

---

Usage Instructions

General Syntax

xk <command> [subcommand] [options]

Commands Overview

• init: Initialize the zettelkasten.
• insert: Create a new zettel.
• ls: List all zettels.
• rm: Remove a zettel.
• mv: Rename (move) a zettel.
• path: Get the path to a zettel or the zettelkasten.

Reference Commands

• ref insert: Add a reference to another zettel.
• ref ls: List references in a zettel.
• ref rm: Remove a reference from a zettel.

Tag Commands

• tag insert: Add a tag to a zettel.
• tag ls: List tags of a zettel.
• tag rm: Remove a tag from a zettel.

Git Commands

• git init: Initialize a Git repository in the zettelkasten.
• git : Run Git commands in the zettelkasten directory.
• git publish: Add, commit, and push changes.

User Scripts

• script [args]: Run a user-defined script.

---

Detailed Documentation

Zettelkasten Structure

Your zettelkasten directory (by default ~/.local/xettelkasten/my-zettel-kasten) will have the following structure:

my-zettel-kasten/
├── zettel1/
│   ├── zettel.tex
│   ├── references
│   └── tags
├── zettel2/
│   ├── zettel.tex
│   ├── references
│   └── tags
├── preamble.sty
├── xettel.cls
└── README.md

• zettel.tex: The LaTeX document for the zettel.
• references: A file containing references to other zettels.
• tags: A file containing tags associated with the zettel.
• preamble.sty: Shared LaTeX preamble.
• xettel.cls: Custom LaTeX class for zettels.
• README.md: A readme file for your zettelkasten.

Configuration Files

• Default Configuration: Found in lib/default_config. Contains default settings.
• User Configuration: Create ~/.config/xk/config to override defaults.

Example ~/.config/xk/config:

ZETTEL_DATA="$HOME/Documents/zettelkasten"
LOG_FILE="$HOME/.local/share/xk/log.txt"

Templates

Customize templates in etc/templates/:

• Zettel Template: zettel.tex
• LaTeX Preamble: preamble.sty
• Zettel Class: xettel.cls

Command Explanations

Initialize the Zettelkasten

xk init

Initializes a new zettelkasten with default templates and configuration.

Create a New Zettel

xk insert -z "Zettel Name"

• -z: Name of the zettel (spaces will be replaced with underscores).

List Zettels

xk ls

Lists all existing zettels.

Remove a Zettel

xk rm -z "Zettel Name"

Deletes the specified zettel and its contents.

Rename (Move) a Zettel

xk mv -z "Old Name" -n "New Name"

• -z: Current name of the zettel.
• -n: New name for the zettel.

Get Zettel Path

xk path -z "Zettel Name"

Outputs the full path to the specified zettel.

Reference Management

Add a Reference

xk ref insert -z "Zettel Name" -r "Reference Name"

Adds a reference from "Zettel Name" to "Reference Name".

List References

xk ref ls -z "Zettel Name"

Displays all references in the specified zettel.

Remove a Reference

xk ref rm -z "Zettel Name" -r "Reference Name"

Removes the specified reference from the zettel.

Tag Management

Add a Tag

xk tag insert -z "Zettel Name" -t "Tag Name"

Adds a tag to the specified zettel.

List Tags

xk tag ls -z "Zettel Name"

Displays all tags associated with the zettel.

Remove a Tag

xk tag rm -z "Zettel Name" -t "Tag Name"

Removes the specified tag from the zettel.

Git Integration

Initialize Git Repository

xk git init

Initializes a Git repository in the zettelkasten directory.

Publish Changes

xk git publish

Adds all changes, commits with a timestamp message, and pushes to the remote repository.

Run Git Commands

xk git <git-command> [args]

Runs the specified Git command in the zettelkasten directory.

User Scripts

Run a User Script

xk script <script_name> [args]

Executes a user-defined script located in:

• User Scripts: ~/.config/xk/userscripts/
• Built-in Scripts: <installation_path>/share/xk/userscripts/

Note : User-defined scripts are prioritized over the built-in scripts, so functionality of builtins can be overriden by defining a custom script with the same name.

---

Advanced Usage

Custom LaTeX Integration

The zettel LaTeX files use a custom class (xettel.cls) and preamble (preamble.sty) for consistent formatting.

• Edit the Preamble: Modify preamble.sty to change the formatting, packages, or commands used in all zettels.
• Customize the Zettel Class: Update xettel.cls to alter the document class settings.

Environment Variables and Configuration

You can adjust various settings by editing the configuration files or exporting environment variables:

• ZETTEL_DATA: The root directory of your zettelkasten.
• LOG_FILE: Location of the log file for xk commands.
• AUTHOR: Author name used in bibliographic entries.

Contributing

Contributions are welcome! If you'd like to contribute:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request with a detailed description.

---

Support

If you encounter any issues or have questions, feel free to open an issue on the GitHub repository.

GitHub Repository

---

Happy Zetteling!