Emacs front-end for Obsidian Notes.
- Installation
- About Obsidian.el
- How does obsidian.el work?
- Why obsidian.el and not…
- Versioning
- Contributing
- Gratitude
Obsidian.el is available from MELPA or MELPA Stable and can be installed with:
M-x package-install RET obsidian RET
Put this in your init.el:
(require 'obsidian)
(obsidian-specify-path "~/MY_OBSIDIAN_FOLDER")
;; If you want a different directory of `obsidian-capture':
(setq obsidian-inbox-directory "Inbox")
;; Clicking on a wiki link referring a non-existing file the file can be
;; created in the inbox (t) or next to the file with the link (nil).
;; Default: t - creating in the inbox
;(setq obsidian-wiki-link-create-file-in-inbox nil)
;; You may want to define a folder for daily notes. By default it is the inbox.
;(setq obsidian-daily-notes-directory "Daily Notes")
;; Directory of note templates, unset (nil) by default
;(setq obsidian-templates-directory "Templates")
;; Daily Note template name - requires a template directory. Default: Daily Note Template.md
;(setq obsidian-daily-note-template "Daily Note Template.md")
;; Define obsidian-mode bindings
(add-hook
'obsidian-mode-hook
(lambda ()
;; apply a template from the directory specified by obsidian-tempaltes-directory
;("C-c C-t" . obsidian-apply-template)
;; Replace standard command with Obsidian.el's in obsidian vault:
(local-set-key (kbd "C-c C-o") 'obsidian-follow-link-at-point)
;; Use either `obsidian-insert-wikilink' or `obsidian-insert-link':
(local-set-key (kbd "C-c C-l") 'obsidian-insert-wikilink)
;; Following backlinks
(local-set-key (kbd "C-c C-b") 'obsidian-backlink-jump)))
;; Optionally you can also bind a few functions:
;; replace "YOUR_BINDING" with the key of your choice:
(global-set-key (kbd "YOUR_BINDING") 'obsidian-jump) ;; Opening a note
(global-set-key (kbd "YOUR_BINDING") 'obsidian-capture) ;; Capturing a new note in the inbox
(global-set-key (kbd "YOUR_BINDING") 'obsidian-daily-note) ;; Creating daily note
;; Activate detection of Obsidian vault
(global-obsidian-mode t)Or using use-package:
(use-package obsidian
:ensure t
:demand t
:config
(obsidian-specify-path "~/MY_OBSIDIAN_FOLDER")
(global-obsidian-mode t)
:custom
;; This directory will be used for `obsidian-capture' if set.
(obsidian-inbox-directory "Inbox")
;; Create missing files in inbox? - when clicking on a wiki link
;; t: in inbox, nil: next to the file with the link
;; default: t
;(obsidian-wiki-link-create-file-in-inbox nil)
;; The directory for daily notes (file name is YYYY-MM-DD.md)
(obsidian-daily-notes-directory "Daily Notes")
;; Directory of note templates, unset (nil) by default
;(obsidian-templates-directory "Templates")
;; Daily Note template name - requires a template directory. Default: Daily Note Template.md
;(setq obsidian-daily-note-template "Daily Note Template.md")
:bind (:map obsidian-mode-map
;; apply a template from the directory specified by obsidian-tempaltes-directory
;("C-c C-t" . obsidian-apply-template)
;; Replace C-c C-o with Obsidian.el's implementation. It's ok to use another key binding.
("C-c C-o" . obsidian-follow-link-at-point)
;; Jump to backlinks
("C-c C-b" . obsidian-backlink-jump)
;; If you prefer you can use `obsidian-insert-link'
("C-c C-l" . obsidian-insert-wikilink)))Optionally you can specify obsidian-inbox-directory, it will be used by obsidian-capture to
store new notes into. If you don’t set it the root folder of your Obsidian vault will be used.
I wanted to work with Obsidian Notes using Emacs. Obviously you already can open your Obsidian folder and start editing markdown files with Emacs. But I want to improve that and split the responsibilities between Emacs and Obsidian the way it makes sense for an Emacs user.
- Sync
- Mobile client (of course, and that’s where Obsidian beats anything else in Emacs)
- Complex exploring (graph views etc)
- All the things done with complex plugins
Obsidian.el must empower us to stay in Emacs for things that make sense in Emacs:
- [X] Creating and editing notes with convenient autocomplete for tags and links (nothing will ever compare to Emacs in terms of editing power)
- [X] Jumping between notes
- [X] Searching all notes
- [X] Finding all notes with a tag
- [X] Following backlinks
- [ ] Viewing backlinks in a separate list
When all of the above is ready we will almost never need the Obsidian app on desktop, but will still be able to use it on mobile or when specifically needed.
When you require obsidian.el via use-package or in other ways (see snippet above), you have to specify the root folder of your Obsidian Notes vault. If global-obsidian-mode is enabled and if you specified the root folder, each time you open a markdown buffer it checks, if that file is part of your Obsidian Notes vault. If it is obsidian-mode minor mode is activated for this buffer.
Once the obsidian-mode is activated obsidian.el scans all markdown files in the vault for tags and links (links still WIP), and stores these lists in it’s global variables. It also adds company-mode backends to suggest links and tags for completion.
Hydra menu
When Hydra is installed, obsidian-hydra will be defined such that it can be used for bindings:
(bind-key (kbd "C-c M-o") 'obsidian-hydra/body 'obsidian-mode-map)
Including hidden dot files
Obsidian does not track hidden files; obsidian.el can be configured to either track them or ignore them by setting the value of `obsidian-include-hidden-files`.
You can update the lists of tags, links etc. manually if it’s lagging for some reason by running an interactive command:
M-x obsidian-update RET
Obsidian.el implements a custom command obsidian-follow-link-at-point which correctly follows markdown and wiki links generated by the Obsidian App. In the install example above this command is bound to C-c C-o in obsidian-mode.
M-x obsidian-follow-link-at-point RET
Note that the Obsidian app replaces spaces with %20 when inserting markdown links, and doesn’t do that when inserting wiki links. Obsidian.el follows this convention to maximize compatibility:
Markdown link with spaces: [2-sub with spaces and буквы](subdir/2-sub%20with%20spaces%20and%20буквы.md)
Wikilink with spaces: [[Subdir/2-sub with spaces and буквы]]Both these types of links are correctly handled by obsidian-follow-link-at-point.
You can quickly jump to backlinks to current file using obsidian-backlink-jump
M-x obsidian-backlink-jump RET
Obsidian doesn’t insert relative path by default, only does it when there are multiple files with the same name. obsidian-follow-link-at-point handles this correctly. Every time you follow a link it checks, if there’s only one match for the filename linked. If there’s just one it simply opens that file. If there’s more than one it prompts you to select which file to open.
When inserting links, two different formats can be used to specify the file: the filename alone, or the path to the file within the Obsidian vault. The default is to only use the filename, but this behavior can be changed by setting the variable obsidian-links-use-vault-path to t. Alternately, using the prefix argument before the call to insert a link will toggle this behavior, inserting a link with the format opposite of this variable.
There are two commands to insert links obsidian-insert-link and obsidian-insert-wikilink, you can choose one depending on your preferred link format:
Example: [Link description](path/to/file.md)
M-x obsidian-insert-link RET
Note, that when you insert a link to file that has spaces in it’s name, like “facts about inserting links.md”, Obsidian app would html-format the spaces, meaning the link will look like
[facts](facts%20about%20inserting%20links.md)Obsidian.el follows this convention and does the same when inserting markdown links. obsidian-follow-link-at-point handles this correctly.
Example: [[path/fo/file.md|Link description]]
M-x obsidian-insert-wikilink RET
Quickly jump between notes using obsidian-jump
M-x obsidian-jump RET
If you have YAML front matter in your note, Obsidian.el will find aliases in it and add them to the obsidian-jump selection. Both aliases and alias keys are supported.
Use obsidian-capture. If you specified obsidian-inbox-directory, it will create new notes in this directory. Otherwise in your Obsidian vault root directory:
M-x obsidian-capture RET
Use obsidian-search to look for a string or a regular expression:
M-x obsidian-search RET query RET
Use obsidian-tag-find to list all notes that contain a tag. Let’s you choose a tag from list of all tags:
M-x obsidian-tag-find RET
Use obsidian-move-file to move current note to another folder:
M-x obsidian-move-file RET
Obsidian.el has a basic template support, where the Obsidian app’s template placeholders can be used, without customization. {{title}}, {{date}}, and {{time}} can be used. {{title}} is the name of the file without the extension.
While the daily notes can have an automatic template (see the config examples), for every other file templates must be applied manually, by calling `obsidian-apply-template`.
- [X] Specify Obsidian folder and save it in variables
- [X] Enumerate files in the Obsidian folder and save a list
- [X] Run the scan when entering obsidian-mode
- [X] Functions to scan notes for tags
- [X] Get full list of all tags
- [X] company-backend with tags
- [X] commands to insert links in markdown and wikilink
- [X] Capture command to create a new note in Obsidian folder
- [X] Obsidian minor for matching .md files
- [X] Jumping between notes
- [X] Following links
- [X] Following backlinks
Easy. When on desktop they are simply not Emacs. Not even Obsidian itself. Emacs beats anything else for things that it is built for. But you know this already, otherwise you wouldn’t be here.
The answer is mostly the same for all of them. Mobile support. Or rather — NO mobile support. I don’t buy into the story that “you don’t really need your PKM system on mobile”, and “serious work is done only on desktop” etc. These are just excuses for the impossibility of building a full-fledged mobile version of Emacs.
So there were two ways to go about it: build a mobile app for something like org-roam (which would be cool, but is above my front-end skills) or build a light-weight Emacs client for something like Obsidian. I chose the simpler task.
The project uses break versioning, meaning that upgrading from 1.0.x to 1.0.y will always be safe, upgrading from 1.x.x to 1.y.x might break something small, and upgrade from x.x.x to y.x.x will break almost everything.
PRs and issues are very welcome. In order to develop locally you need to install eldev. After that you can run make commands, in particular make test and make lint to make sure that your code will pass all MELPA checks.
- The work on Obsidian.el was made considerably easier and definitely more fun thanks to the great work of Magnar Sveen and his packages dash.el and s.el. Thank you for making Elisp almost as convenient as Clojure!
- During the development of Obsidian.el I have learned and copied from the code of the amazing org-roam package. Thank you!