[[https://melpa.org/#/obsidian][file:https://melpa.org/packages/obsidian-badge.svg]] [[https://stable.melpa.org/#/obsidian][file:https://stable.melpa.org/packages/obsidian-badge.svg]]
Emacs front-end for [[https://obsidian.md/][Obsidian Notes]].
Table of Contents :toc:
[[#installation][Installation]]
[[#about-obsidianel][About Obsidian.el]]
[[#how-does-obsidianel-work][How does obsidian.el work?]]
[[#why-obsidianel-and-not][Why obsidian.el and not...]]
[[#versioning][Versioning]]
[[#contributing][Contributing]]
[[#gratitude][Gratitude]]
Installation Obsidian.el is available from [[https://melpa.org][MELPA]] or [[https://stable.melpa.org/#/obsidian][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 () ;; 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 [[https://github.com/jwiegley/use-package][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 ;(obsidian-daily-note-template "Daily Note Template.md") :bind (:map obsidian-mode-map ;; 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 useobsidian-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.
** What should we keep doing in Obsidian?
** What should be possible to do in Emacs? Obsidian.el must empower us to stay in Emacs for things that make sense in Emacs:
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.
** company-mode completion [[./resources/tag-completion.png]]
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 [[http://company-mode.github.io/][company-mode]] backends to suggest links and tags for completion.
** [[https://github.com/abo-abo/hydra][Hydra]] menu
When [[https://github.com/abo-abo/hydra][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)
[[./resources/hydra-menu.png]]
** 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.
** Manual re-scan 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
** Following links 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 буквы
Wikilink with spaces: [[Subdir/2-sub with spaces and буквы]]
Both these types of links are correctly handled by ~obsidian-follow-link-at-point~.
** Following backlinks You can quickly jump to backlinks to current file using ~obsidian-backlink-jump~
M-x obsidian-backlink-jump RET
*** Multiple matches 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.
** Inserting links [[./resources/insert-link.png]]
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:
*** Inserts a link in Markdown format Example: ~Link description~
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
Obsidian.el follows this convention and does the same when inserting markdown links. ~obsidian-follow-link-at-point~ handles this correctly.
*** Insert a link in wikilink format Example: ~[[path/fo/file.md|Link description]]~
M-x obsidian-insert-wikilink RET
** Jumping between notes Quickly jump between notes using ~obsidian-jump~
M-x obsidian-jump RET
*** Aliases 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.
** Capturing new note 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
** Searching notes Use ~obsidian-search~ to look for a string or a regular expression:
M-x obsidian-search RET query RET
** Finding all notes with a tag 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
** Move note to another folder Use ~obsidian-move-file~ to move current note to another folder:
M-x obsidian-move-file RET
** Templates
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.
*** Development tasks
[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
Why obsidian.el and not... ** Obsidian App itself, Athens Research or any other great app? 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.
** Org-roam or any other great Emacs libraries? 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.
Versioning The project uses [[https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md][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.
Contributing PRs and issues are very welcome. In order to develop locally you need to install [[https://github.com/doublep/eldev/][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.
Gratitude
The work on Obsidian.el was made considerably easier and definitely more fun thanks to the great work of [[https://github.com/magnars][Magnar Sveen]] and his packages [[https://github.com/magnars/dash.el][dash.el]] and [[https://github.com/magnars/s.el][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 [[https://github.com/org-roam/org-roam][org-roam]] package. Thank you!