Skip to content
/ md-roam Public

Use Org-roam with markdown files by adding Md-roam as a plug-in. Mix org and markdown files in a single Org-roam database.

License

Notifications You must be signed in to change notification settings

nobiot/md-roam

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

License GPL 3

Use Org-roam with Markdown files by adding Md-roam to it. Md-roam extends the features and functions provided by Org-roam to support Markdown files. Mix Markdown with Org files in a single Org-roam database for your Zettelkasten-style note-taking and backlinks.

Screen shot showing main features of Org-roam supported by Md-roam

  1. Title and other meta data in the YAML front matter

  2. #tag support to categorize notes

  3. Note as a reference material (literature notes or notes on website) with roam_refs:

  4. Aliases of a note with roam_aliases: in the YAML array syntax with ["alias1", "alias two"]

  5. Link with [[wiki-link]] syntax that appears as a backlink and "in-line search" with Company or Corfu; you can use the title or an alias of a note

  6. Citations with Pandoc style [@citekey], @citekey -@citekey, etc. for Markdown files; for Org, Org-ref or Org-cite styles as Org-roam support them

  7. Markdown and Org citations for reference materials; they appear in the reflink section

  8. Backlinks between Org and Markdown files both ways; you can mix both formats in a single Org-roam database

  9. Org-roam standard backlink buffer with no modification to the database schema and backlink buffer

  10. Graph and note preview by Org-roam-ui (ORUI)

Graph and note preview by ORUI

Getting Started

Installation

This package is not available on MELPA or ELPA. Manual installation is required.

Download or clone this repo, put the .el file into your load-path, and put something like this in your init file.

(add-to-list  'load-path "path/to/md-roam")

Basic Configuration

Org-roam must be configured before Md-roam. As a minimal configuration for Md-roam, these should be sufficient:

  • (setq org-roam-file-extensions '("org" "md")) ; enable Org-roam for a markdown extension
  • (md-roam-mode 1) ; md-roam-mode needs to be active before org-roam-db-sync
  • (setq md-roam-file-extension "md") ; Default is "md". Specify an extension such as "markdown"
(require 'org-roam)
(setq org-roam-directory (file-truename "path/to/org-roam-directory"))
;; file-truename is optional; it seems required when you use symbolic
;; links, which Org-roam does not resolve
(setq org-roam-file-extensions '("org" "md")) ; enable Org-roam for a markdown extension
(add-to-list 'load-path "path/to/md-roam") ; installation as above
(require 'md-roam)
(md-roam-mode 1) ; md-roam-mode must be active before org-roam-db-sync
(setq md-roam-file-extension "md") ; default "md". Specify an extension such as "markdown"
(org-roam-db-autosync-mode 1) ; autosync-mode triggers db-sync. md-roam-mode must be already active

Additionally, you can use org-roam-capture-templates for Markdown files like this:

(add-to-list 'org-roam-capture-templates
    '("m" "Markdown" plain "" :target
        (file+head "%<%Y-%m-%dT%H%M%S>.md"
"---\ntitle: ${title}\nid: %<%Y-%m-%dT%H%M%S>\ncategory: \n---\n")
    :unnarrowed t))

For interactive commands, you can use Org-roam's standard ones. There is no specific commands for Md-roam:

;;;; Org-roam
(define-key global-map (kbd "C-c n f") #'org-roam-node-find)
(define-key global-map (kbd "C-c n c") #'org-roam-capture)
(define-key global-map (kbd "C-c n i") #'org-roam-node-insert)
(define-key global-map (kbd "C-c n l") #'org-roam-buffer-toggle)

"In-line search" with Company and Corfu

With Md-roam, you can use completion-at-point for wiki links within Org-roam. Md-roam currently does not implement support for org-roam-complete-everywhere. I will not be able to provide a fix any time soon -- please consider this option unsupported (see issue #82)

Corfu animation

For Company, there is no specific configuration. Md-roam implements completion-at-point (or capf); use it as a Company backend. For more detail, refer to Company's documentation.

For Corfu, add something like this below to get Tab to work for corfu-mode. By default, Markdown-mode's Tab function does not use complete-at-point like Org-mode's equivalent does.

(with-eval-after-load 'markdown-mode
  (advice-add #'markdown-indent-line :before-until #'completion-at-point))

License

Md-Roam: Copyright © Noboru Ota Org-Roam: Copyright © Jethro Kuan and contributors.

Distributed under the GNU General Public License, Version 3