Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tmalsburg/mwk.el

Yet another Zettelkasten system for Emacs
https://github.com/tmalsburg/mwk.el

elisp emacs note-taking org-mode zettelkasten

Last synced: about 10 hours ago
JSON representation

Yet another Zettelkasten system for Emacs

Awesome Lists containing this project

README 

        
#+TITLE: Magic Wikikasten (MWK) – The Lazy Person’s Zettelkasten System



A simple and low-barrier Zettelkasten system designed to let you write without distraction.



** Key features

- Any plain old org-document with a ~#+TITLE:~ property can be a full citizen in your Zettelkasten.  No special syntax or meta information needed.

- The Zettelkasten is simply a directory containing org-documents.  Each document corresponds to a topic.

- Links between topics are created automagically.  No need to create and manage links by hand.  No need to update links when their target document changes.

- No persistent index needed.  MWK uses silversearcher (fast!) to see what’s the current state of affairs in your Zettelkasten.

- MWK aims to be an (almost) zero-configuration solution.  The only thing that needs to be configured is the location of your Zettelkasten.



* Status

This software is quite young and still a bit rough around the edges.  However, it’s also feature-complete (for my taste at least) and ready for daily use.



*Known issues:*

1. MWK doesn’t work reliably in conjunction with [[https://melpa.org/#/emojify][emojify.el]].  When links are displayed, Emacs sometimes runs with 100% CPU load.  There’s probably an incompatibility in how MWK and emojify use font-lock.

2. A bunch of compiler warnings.



** How does it work?

1. The key distinguishing feature is that *links are created automatically* when a string that you type matches an existing topic’s name.  Links are not written out in org syntax but are dynamically created in Emacs (via Font Lock) and are not part of the file.  So if a new document is created and other documents already mention its topic, no new links need to be created.  Links to the new document will instead magically appear.



   Zettelkasten links are similar to org’s [[https://orgmode.org/manual/Radio-Targets.html#Radio-Targets][radio targets]] except that Zettelkasten links work across documents and that you don’t need to update Zettelkasten links manually.  However, unlike radio targets, Zettelkasten links do not export to PDF, HTML, etc.  But that’s a feature since the content of a Zettelkasten is typically private and should not become available to readers of an individual exported document.



   Having to create links manually and explicitly was a major source of frustration for me when working with other Zettelkasten systems.  With dynamic links, the user can focus on writing and doesn’t need to give any attention to the Zettelkasten.  



   Bonus: Zettelkasten links can also be displayed in other documents that are living outside the Zettelkasten, such as LaTeX and Markdown documents, e-mails, Emacs’ inline documentation, and so on.  The content of your Zettelkasten will always be at your fingertips.



2. *All documents belonging to a Zettelkasten are located in a single directory* (~mwk-directory~).  A Zettelkasten document is a simple org file that minimally defines a ~#+TITLE:~ property which specifies its topic.  The string in the title will be used for finding references to that document and for creating links.  Since a title property is enough, many of your existing documents can become part of your Zettelkasten simply by being copied to the Zettelkasten directory. 



3. If there are multiple synonymous ways to refer to a topic, a list of so-called *wiki names can be specified using the* ~#+WIKINAMES:~ *property*.  If present, only the wiki names will be used for finding references and creating links (not the title).  Wiki names are comma-separated regular expressions.  An example is the wiki name ~eye.?tracking~ to capture multiple different spellings: /eye tracking/, /eyetracking/ and /eye-tracking/.  Or ~backups?~ to capture both /backup/ and /backups/ and /Backup/ at the beginning of the sentence.  Wiki names are case-insensitive unless they contain uppercase letters in which case they become case-sensitive (e.g., ~Wi-Fi~).  If your wiki name contains characters that have special meaning in regular expression syntax, you need to escape them, e.g., to match ~R^2~ in documents, use the wiki name ~R\^2~.  Regular expressions are powerful, but it’s also easy to shoot yourself in the foot if you get too fancy.



4. *Three helm commands help you navigate your Zettelkasten*:

  - The Helm command ~helm-mwk-topics~ can be used to *find existing topics in your Zettelkasten*.  This command can also be used to create new topics.  Simply type the title of a new topic and hit enter.

  - The Helm command ~helm-mwk-references~ can be used to *find back-references*, i.e. Zettelkasten topics with references to the current topic.  This is the signature feature of the Zettelkasten system which gives it much of its power.

  - The Helm command ~helm-mwk-search~ can be used for a *full-text search in your Zettelkasten*.



Many other features could be added to this system but most would detract from the main design goal: simplicity.



* Architecture

Magic Wikikasten (MWK) consists of three main components:

1. A global minor mode, ~global-mwk-mode~, that watches the Zettelkasten and keeps an up-to-date list of topics in memory.  (Unlike org-roam, MWK doesn’t store an index on disk.)

2. A local minor mode, ~mwk-mode~, that creates links in the current document, which may be a Zettelkasten document or something else outside the Zettelkasten.

3. Three Helm commands for navigating your Zettelkasten (~helm-mwk-topics~), discovering connections (~helm-mwk-references~), and generally finding stuff (~helm-mwk-search~).



Behind the scenes, MWK uses [[https://github.com/ggreer/the_silver_searcher][silversearcher]] for searching which is super fast and much faster than opening and scanning files in Emacs.  As a result, this MWK should work okay with large Zettelkästen containing many documents.



** Comparison with [[https://www.orgroam.com/][org-roam]]

While org-roam (v1) was the main inspiration for this project, MWK has a different focus.  Org-roam aims to be a complete and comprehensive Zettelkasten solution that is highly configurable and extensible.  MWK, in contrast, is intended to be simple and easy to learn (hence “the lazy person’s Zettelkasten”).  If you’d like to buy heavily into the Zettelkasten idea, org-roam might be the better solution for you.  MWK is a good low-barrier starting point if you’d like to get your feet wet with the Zettelkasten idea.



* Installing MWK

1. Magic Wikikasten uses [[https://github.com/ggreer/the_silver_searcher][silversearcher]] (the ~ag~ command) to scan the Zettelkasten.  On Ubuntu-like systems it can be installed via: ~sudo apt install silversearcher-ag~

2. MWK uses [[https://emacs-helm.github.io/helm/][Helm]] for navigating the Zettelkasten.  See [[https://emacs-helm.github.io/helm/#getting-started][here]] for installation instructions.

3. Finally, make sure that ~mwk.el~ is in your ~load-path~.  MWK is currently not available via the usual package repositories but it can be installed directly from GitHub using straight.el:



#+BEGIN_SRC elisp

(straight-use-package

 '(mwk :type git :host github :repo "tmalsburg/mwk.el"))

#+END_SRC



* Configuration

There is a single customization variable, ~mwk-directory~, that specifies where the Zettelkasten is located on your file system.  A complete configuration is then as simple as this:



#+BEGIN_SRC elisp :eval no

(require 'mwk)



(setq mwk-directory "/home/user/zettelkasten")



(global-mwk-mode 1)

#+END_SRC



In addition, you might want to create some key bindings for the following commands:

- ~helm-mwk-topics~: Searches for topics in your Zettelkasten

- ~helm-mwk-references~: Searches for back-references, i.e. references to the current topic

- ~helm-mwk-search~: Full text search in your Zettelkasten

- ~mwk-flash-links~: Display links to Zettelkasten topics for 3 seconds.



* How to use MWK?

** Create a first Zettelkasten document:

Execute ~helm-mwk-topics~, type the title of a new topic, and hit enter.  Make sure you save this file after editing.



Example: ~M-x helm-mwk-topics~ followed by ~My first topic RET~ creates the following new document in your Zettelkasten:

#+BEGIN_EXAMPLE

#+TITLE: My first topic

#+WIKINAMES: |

#+END_EXAMPLE



Either add some wiki names or delete the ~#+WIKINAMES:~ property.  When you save the document, MWK will automatically update its index of topics.



** Create a second Zettelkasten document:

Same as above.



** Open an existing Zettelkasten document:

Same as above (e.g., ~M-x helm-mwk-topics~, enter title and select topic using the return key.



** Create a reference to an existing Zettelkasten document:

Nothing you need to do.  Just type a string that is matched by one of the topic’s wiki names (or title).  No need to create explicit org links.  Effectively you will create references on the fly without even thinking about it, just by writing prose.  That’s the magic in Magic Wikikasten.



** Display links to Zettelkasten documents:

In documents belonging to your Zettelkasten, links will be displayed by default.  In other documents you can execute ~M-x mwk-flash-links~ to show links for 3 seconds during which they will be clickable.  Alternatively, enable ~mwk-mode~ to display links permanently.



** Hide links to Zettelkasten documents:

Disable ~mwk-mode~.



** Find references to the current Zettelkasten document:

Execute ~M-x helm-mwk-references~.  Ideally this command is bound to some key combination for easy access.



** Search in all documents belonging to the Zettelkasten:

Execute ~M-x helm-mwk-search~, and enter a string.



* Specific use cases

** You’re writing a document (e.g. a LaTeX manuscript) and need quick access to your notes about various relevant topics:

Three options:

- Activate ~mwk-mode~ and references to topics in your Zettelkasten will become links.

- Alternatively, use ~mwk-flash-links~ to display links for just a moment during which they will be clickable.

- Execute ~helm-mwk-topics~ to search for a topic.



** You figured out how to compile Emacs from source and would like to save this information for the future:

Execute ~helm-mwk-topics~, type “Compiling Emacs”, hit enter, write down the recipe in the new org file, and save.



** Integrate helm-bibtex’ and ivy-bibtex’ note-taking systems with your MWK Zettelkasten:

Add this to your helm/ivy-bibtex configuration:

#+BEGIN_SRC elisp

(setq bibtex-completion-notes-path mwk-directory)

(setq bibtex-completion-notes-template-multiple-files

      "#+TITLE: ${author-or-editor-abbrev} (${year}): ${title}\n#+WIKINAMES: ${=key=}\n\n")

#+END_SRC

Then search for an article via ~helm-bibtex~ or ~ivy-bibtex~, select “Edit notes”, and a new note will be created in your Zettelkasten (or the existing note will be opened).  BibTeX keys in other documents will automatically become links to existing notes in your Zettelkasten when you activate ~mwk-mode~ or execute ~mwk-flash-links~.