agendafs

A filesystem for your calendar.

commit ad0e031ba8c6a7ddd3dab17c0761459a692e747f
parent f0c830889272d79bc0710e8cf68a391d541ed1e2
Author: Marc Coquand <mccd@bogo.bogo>
Date:   Thu,  6 Nov 2025 17:24:35 +0100

README

Diffstat:
M
README.md
 | 
48
++++++++++++++++++++++++++----------------------

1 file changed, 26 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
@@ -36,9 +36,10 @@ make
 make install
 ```
 
-## Basic principles
+## Basic Principles
 
-Agendafs uses a [vdir storage](https://pimutils.org/specs/vdir/) as a backend to allow users to sync VJOURNAL entries to a remote caldav server.
+Agendafs uses a [vdir storage](https://pimutils.org/specs/vdir/) as a backend
+to allow users to sync VJOURNAL entries to a remote caldav server.
 
 Agendafs scans the vdir directory for VJOURNAL entries to populate the
 file tree. Each VJOURNAL entry is represented as a file or directory in
@@ -57,7 +58,7 @@ To mount a vdir storage with Agendafs:
 mount.agendafs -o vdir=<vdir directory> <mountpoint>
 ```
 
-See `agendafs(8)` for full list of options and examples.
+See [agendafs(8)](https://git.sr.ht/~marcc/agendafs/blob/main/agendafs.8.scd) and [agendafs-examples(7)](https://git.sr.ht/~marcc/agendafs/blob/main/agendafs-examples.7.scd) for a full list of options and examples.
 
 
 ### Limitations
@@ -74,30 +75,31 @@ currently not enforce any file size limit.
 ## Motivation
 
 Note-taking tools like Obsidian and Logseq have great syncing capabilities,
-but they restrict you to only those editors. I wanted a solution that is more
-Unixy, allowing me to combine tools and build automation on top. However,
-when I stored my notes in plain-text, I struggled to find a good solution
-for syncing and editing notes on other devices. Since I had signed up to an
-email provider, and thus had a caldav server for my calendar, I thought it'd
-be a great place to store my notes. Storing notes in ical-format means that
-I can also take advantage of mobile apps for editing my notes, such as jtx
-Board on Android.
-
-Agendafs also takes advantage of Xattributes to store categories (aka tags),
-classification (public vs private) and allows you to store arbitrary metadata
-to the file. This means that it frees you from just using one file-format
-while still giving you capabilities to link notes, either via directories
-or via categories (sibling linking exists in the ical spec, but this is
-not supported yet). This means Agendafs pairs well with CLI tools,  file
-explorers like nnn, lf, ranger and also editors like Kakoune and Neovim.
-
-Of course, you can also ignore all of that and just use Agendafs
+but they restrict you to only those editors. I wanted a solution that is
+more Unixy, and allow me to use my favorite CLI tools. Plain-text notes
+seemed like the obvious solution, but I struggled to find a good solution
+for syncing and editing notes on other devices. Caldav makes for a great
+place to store notes, since many already have a provider. Storing notes in
+ical-format means that I can also take advantage of mobile apps for editing
+my notes, such as jtx Board on Android.
+
+Agendafs also have some features that are too unergonomic on regular
+filesystems. It makes full use of Xattributes to store categories,
+classification (public vs private) and any other arbitrary metadata to the
+file. This means that it frees you from just using one file-format while
+still giving you capabilities to link notes, either via directories or
+via categories (sibling linking exists in the ical spec, but this is not
+supported yet). This also makes it easy to pair Agendafs  with CLI tools,
+file explorers like nnn, lf, ranger and also editors like Kakoune and Neovim. For example, you could easily extend `lf` to show if a file is draft or not.
+I documented in [examples] what this might look like
+
+Of course, you can also ignore those features and just use Agendafs
 as a way to just backup your [todotxt](http://todotxt.org/) or
 [jrnl](https://jrnl.sh/en/stable/).
 
 ## Appendix
 
-### VJOURNAL support in Nextcloud calendar
+### VJOURNAL support in Nextcloud calendars
 
 To have vjournal support on Nextcloud, I needed to create the calendar manually. This is probably also required if you use Fastmail.
 
@@ -151,3 +153,5 @@ Usage: `find_by_category MY_CATEGORY | nnn`
 ### Why C?
 
 I started this project to improve my C skills.
+
+[examples]: https://git.sr.ht/~marcc/agendafs/blob/main/agendafs-examples.7.scd