{"id":13750459,"url":"https://github.com/nobiot/md-roam","last_synced_at":"2025-04-05T16:08:49.507Z","repository":{"id":38089792,"uuid":"249169624","full_name":"nobiot/md-roam","owner":"nobiot","description":"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.","archived":false,"fork":false,"pushed_at":"2024-04-06T20:02:33.000Z","size":44984,"stargazers_count":318,"open_issues_count":8,"forks_count":13,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-04-06T21:21:10.826Z","etag":null,"topics":["emacs","markdown","org-roam","pkm","roam","zettelkasten"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nobiot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-22T11:32:45.000Z","updated_at":"2024-04-06T21:21:13.055Z","dependencies_parsed_at":"2023-02-11T00:01:05.884Z","dependency_job_id":"7f0019a2-50b1-4761-b6d3-58db7ce04d85","html_url":"https://github.com/nobiot/md-roam","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nobiot%2Fmd-roam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nobiot%2Fmd-roam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nobiot%2Fmd-roam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nobiot%2Fmd-roam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nobiot","download_url":"https://codeload.github.com/nobiot/md-roam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361691,"owners_count":20926643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","markdown","org-roam","pkm","roam","zettelkasten"],"created_at":"2024-08-03T08:00:36.290Z","updated_at":"2025-04-05T16:08:49.475Z","avatar_url":"https://github.com/nobiot.png","language":"Emacs Lisp","funding_links":[],"categories":["Uncategorized","Emacs Lisp","markdown","Tools","Software"],"sub_categories":["Uncategorized"],"readme":"[![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)\n\nUse [Org-roam](https://www.orgroam.com/) with Markdown files by adding Md-roam\nto it.  Md-roam extends the features and functions provided by Org-roam to\nsupport Markdown files. Mix Markdown with Org files in a single Org-roam database\nfor your Zettelkasten-style note-taking and backlinks.\n\n![Screen shot showing main features of Org-roam supported by Md-roam](./images/md-roam-v2-overview.png)\n\n1. Title and other meta data in the YAML front matter\n\n2. `#tag` support to categorize notes\n\n3. Note as a reference material (literature notes or notes on website) with `roam_refs:`\n\n4. Aliases of a note with `roam_aliases:` in the YAML array syntax with `[\"alias1\", \"alias two\"]`\n\n5. 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\n\n6. Citations with Pandoc style `[@citekey]`, `@citekey` `-@citekey`, etc. for Markdown files; for Org, Org-ref or Org-cite styles as Org-roam support them\n\n7. Markdown and Org citations for reference materials; they appear in the reflink section\n\n8. Backlinks between Org and Markdown files both ways; you can mix both formats in a single Org-roam database\n\n9. Org-roam standard backlink buffer with no modification to the database schema and backlink buffer\n\n10. Graph and note preview by [Org-roam-ui (ORUI)](https://github.com/org-roam/org-roam-ui)\n\n![Graph and note preview by ORUI](./images/ORUI.png)\n\n\n# Getting Started\n\n## Installation\n\nThis package is not available on MELPA or ELPA. Manual installation is required.\n\nDownload or clone this repo, put the `.el` file into your load-path, and put\nsomething like this in your init file.\n\n```emacs-lisp\n(add-to-list  'load-path \"path/to/md-roam\")\n```\n\n## Basic Configuration\n\nOrg-roam must be configured before Md-roam. As a minimal configuration for Md-roam, these should be sufficient:\n\n- `(setq org-roam-file-extensions '(\"org\" \"md\")) ; enable Org-roam for a markdown extension`\n- `(md-roam-mode 1) ; md-roam-mode needs to be active before org-roam-db-sync`\n- `(setq md-roam-file-extension \"md\") ; Default is \"md\". Specify an extension such as \"markdown\"`\n\n```emacs-lisp\n(require 'org-roam)\n(setq org-roam-directory (file-truename \"path/to/org-roam-directory\"))\n;; file-truename is optional; it seems required when you use symbolic\n;; links, which Org-roam does not resolve\n(setq org-roam-file-extensions '(\"org\" \"md\")) ; enable Org-roam for a markdown extension\n(add-to-list 'load-path \"path/to/md-roam\") ; installation as above\n(require 'md-roam)\n(md-roam-mode 1) ; md-roam-mode must be active before org-roam-db-sync\n(setq md-roam-file-extension \"md\") ; default \"md\". Specify an extension such as \"markdown\"\n(org-roam-db-autosync-mode 1) ; autosync-mode triggers db-sync. md-roam-mode must be already active\n```\n\nAdditionally, you can use `org-roam-capture-templates` for Markdown files like this:\n\n```emacs-lisp\n(add-to-list 'org-roam-capture-templates\n    '(\"m\" \"Markdown\" plain \"\" :target\n        (file+head \"%\u003c%Y-%m-%dT%H%M%S\u003e.md\"\n\"---\\ntitle: ${title}\\nid: %\u003c%Y-%m-%dT%H%M%S\u003e\\ncategory: \\n---\\n\")\n    :unnarrowed t))\n```\n\nFor interactive commands, you can use Org-roam's standard ones. There is no specific commands for Md-roam:\n\n```emacs-lisp\n;;;; Org-roam\n(define-key global-map (kbd \"C-c n f\") #'org-roam-node-find)\n(define-key global-map (kbd \"C-c n c\") #'org-roam-capture)\n(define-key global-map (kbd \"C-c n i\") #'org-roam-node-insert)\n(define-key global-map (kbd \"C-c n l\") #'org-roam-buffer-toggle)\n```\n\n## \"In-line search\" with Company and Corfu\n\nWith 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](https://github.com/nobiot/md-roam/issues/82))\n\n![Corfu animation](./images/corfu.gif)\n\n\nFor [Company](https://github.com/company-mode/company-mode), 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.\n\nFor [Corfu](https://github.com/minad/corfu), add something like this below to get \u003ckbd\u003eTab\u003c/kbd\u003e to work for `corfu-mode`. By default, Markdown-mode's \u003ckbd\u003eTab\u003c/kbd\u003e function does not use `complete-at-point` like Org-mode's equivalent does.\n\n```emacs-lisp\n(with-eval-after-load 'markdown-mode\n  (advice-add #'markdown-indent-line :before-until #'completion-at-point))\n```\n\n# License\n\nMd-Roam: Copyright © Noboru Ota\nOrg-Roam: Copyright © Jethro Kuan and contributors.\n\nDistributed under the GNU General Public License, Version 3\n\n[org]: https://orgmode.org/\n[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg\n[docs]: https://org-roam.github.io/org-roam/manual/\n[slack]: https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg\n[discourse]: https://org-roam.discourse.group/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnobiot%2Fmd-roam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnobiot%2Fmd-roam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnobiot%2Fmd-roam/lists"}