Update:

I used this for about a year, and it was mostly a good experience, but I decided it doesn't go far enough in the direction described in the "Philosophy" section below. In particular, to avoid broken links, it's necessary to only use supported file types and to make sure that all reorganization of files is done via the tool (as opposed to, say, the Finder). So while the feeling of lock-in is less than when using traditional note management software, it's still there. Also, it's hard to avoid accidentally breaking links from time to time - whether because of bugs, or forgetting to invoke notesdir when moving a file, or interaction with weird iCloud Drive behavior.

My current thinking is that keeping hyperlinks between notes is more trouble than it's worth. Instead, I put a unique ID in the text of each note, and mention that ID in the text of any notes that need to "link" to it. To find a linked note I can just search for the ID with Spotlight/etc. This relatively low-tech approach means that connections between notes are never lost when I convert between file types or move stuff around. It's less convenient than being able to just click a hyperlink, but I don't really need to follow the links in my notes all that often anyway.

About

Notesdir is a command-line tool to help you manage notes that are stored as regular files. It can assist with:

• Link management

  • update references to and from a file when moving it
  • show links and backlinks for a file

• Metadata management

  • store title, true creation date, and tags in each file via mechanisms appropriate to the file type
  • display metadata in unified format

• Querying

  • look for files with or without specific tags

• Templating

  • write Mako templates for quickly creating new notes

• Organizing

  • write rules in Python for organizing directories based on file metadata or relations between files

Philosophy

• You can use any editors you want.
• Notes don't all have to be the same file format. Notesdir can currently parse and update Markdown, HTML, and PDFs; new file type support is straightforward to add; unrecognized file types can coexist peacefully.
• You can organize your files however you want, and reorganize them at will.
• Your notes should remain completely usable without notesdir. In particular, links between notes are just regular relative file paths which can be followed by many text editors, terminals, and browsers.
• You should be able to use just the features of notesdir that you want. The goal is to be more like a library than a framework.
• Notesdir's functionality is all easy to use programmatically. The Python API can be imported into your own scripts. The CLI commands also have options to print output as JSON.

Setup

1. Install Python 3.7 or greater
2. Run pip3 install notesdir
3. Create a .notesdir.conf.py file in your home directory:

from notesdir.conf import *

conf = NotesdirConf(
    # SqliteRepo enables caching, which is important if you have more than a few dozen notes.
    # The sqlite database is just a cache: if you delete it, it'll be rebuilt the next time you
    # run notesdir (but that may take a while).
    repo_conf = SqliteRepoConf(
        # List the directories that contain your notes here.
        # These are searched recursively, you should not also list subdirectories.
        root_paths={'/Users/jacob/Zettel'},

        # Specify a path to store the cache in. The file will be created if it does not exist.
        # If you only have a handful of notes, you can use DirectRepoConf instead of SqliteRepoConf,
        # and omit this line.
        cache_path='/Users/jacob/local-only/notesdir-cache.sqlite3'
    ),

    # This is an optional list of path globs where note templates can be found; it's used
    # by the `notesdir new` command.
    template_globs=["/Users/jacob/Zettel/*/templates/*.mako"]
)

# This is optional. It determines the behavior of the `notesdir organize` command. This config sets
# up a couple rules:
# - If a file has title metadata, use that to set the filename, and use a limited set of characters
#   in the filename
# - If you have attachments organized into ".resources" dirs - for example,
#   a file "foo.md" and "foo.md.resources/bar.png" - make sure the files in the resources dir move
#   when the main file moves.
def path_organizer(info):
    path = rewrite_name_using_title(info)
    return resource_path_fn(path) or path

conf.path_organizer = path_organizer

# This is optional. It tells notesdir not to parse or edit certain files. I store attachments
# to notes in directories named like `filename.resources`, and those attachments would never
# contain metadata or links that I want to query or update, so I skip parsing those.
# These files can still be moved by `organize`, and backlinks are still tracked for them.
def skip_parse(parentpath, filename):
    return filename.endswith('.resources')

conf.repo_conf.skip_parse = skip_parse

That's it! You can run notesdir query to print a list of everything Notesdir currently knows about your notes. (Which may or may not be very much, until you fill in some metadata.) It may take a while the first time, while it builds the cache.

See the full documentation for a walkthrough of all the functionality.