{"id":13750474,"url":"https://github.com/org-roam/org-roam-bibtex","last_synced_at":"2025-04-05T02:12:20.592Z","repository":{"id":42517608,"uuid":"255595349","full_name":"org-roam/org-roam-bibtex","owner":"org-roam","description":" Org Roam integration with bibliography management software","archived":false,"fork":false,"pushed_at":"2024-02-29T19:13:36.000Z","size":2288,"stargazers_count":561,"open_issues_count":27,"forks_count":48,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-05-01T17:16:42.361Z","etag":null,"topics":["bibliography","bibtex","emacs","org-mode","org-roam","references","roam"],"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/org-roam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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,"publiccode":null,"codemeta":null},"funding":{"github":"zaeph","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.me/zaeph","https://www.buymeacoffee.com/mshevchuk"]}},"created_at":"2020-04-14T11:52:06.000Z","updated_at":"2024-05-30T01:30:11.187Z","dependencies_parsed_at":"2023-02-18T19:45:42.585Z","dependency_job_id":"9d85351d-8ff3-4627-8ebd-f9b03a60e4ff","html_url":"https://github.com/org-roam/org-roam-bibtex","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/org-roam%2Forg-roam-bibtex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/org-roam%2Forg-roam-bibtex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/org-roam%2Forg-roam-bibtex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/org-roam%2Forg-roam-bibtex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/org-roam","download_url":"https://codeload.github.com/org-roam/org-roam-bibtex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276189,"owners_count":20912288,"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":["bibliography","bibtex","emacs","org-mode","org-roam","references","roam"],"created_at":"2024-08-03T08:00:36.508Z","updated_at":"2025-04-05T02:12:20.570Z","avatar_url":"https://github.com/org-roam.png","language":"Emacs Lisp","funding_links":["https://github.com/sponsors/zaeph","https://www.paypal.me/zaeph","https://www.buymeacoffee.com/mshevchuk"],"categories":["Emacs Lisp","Tools","Knowledge Management"],"sub_categories":[],"readme":"[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/org-roam/org-roam-bibtex/graphs/commit-activity)\n[![GitHub Release](https://img.shields.io/github/release/org-roam/org-roam-bibtex.svg)](https://github.com/org-roam/org-roam-bibtex/releases/)\n[![MELPA](https://melpa.org/packages/org-roam-bibtex-badge.svg)](https://melpa.org/#/org-roam-bibtex)\n\norg-roam-bibtex\n============\n\n\u003cimg alt=\"ORB logo\" src=\"img/logo-r500.png\" width=\"150\"\u003e\n\nDescription\n---------------\n\nOrg Roam BibTeX (ORB) is an Org Roam extension that integrates [Org\nRoam](https://github.com/jethrokuan/org-roam) with bibliography/citation\nmanagement software: [Org Ref](https://github.com/jkitchin/org-ref), [Helm and\nIvy BibTeX](https://github.com/tmalsburg/helm-bibtex) and\n[Citar](https://github.com/bdarcus/citar).\n\nIt allows users to manage their bibliographical notes using Org Roam and access\nthe notes in `org-roam-directory` via `helm-bibtex`, `ivy-bibtex`,\n`citar-open-notes` or by activation Org-ref `cite:` links and Org-cite\ncitations.\n\nQuick Demonstration 🎬\n---------------\n\u003cimg alt=\"Demo (gif)\" src=\"img/demo.gif\" width=\"700\"\u003e\n\nSee also [a somewhat outdated video demonstration of Org Roam\nv0.2.1](https://www.youtube.com/watch?v=Wy9WvF5gWYg)\n\nArticles\n---------------\nHere is a selection of articles that you may find interesting.\n\n#### Introduction to Org-roam\n- [How To Take Smart Notes With Org-mode](https://blog.jethro.dev/posts/how_to_take_smart_notes_org/) by [@jethrokuan](https://github.com/jethrokuan)\n\n#### Workflow\n- [An Orgmode Note Workflow](https://rgoswami.me/posts/org-note-workflow/) by [@HaoZeke](https://github.com/HaoZeke) (outdated).\n\nImportant news \n---------------------------------\n\n**Org Roam BibTeX has been upgraded to v0.6, which is compatible with Org-roam\nv2.  Please read carefully this README file and [the\nmanual](doc/orb-manual.org) and adjust your configuration files accordingly.\nIn particular, pay attention that the variable `orb-templates` has been\ndeprecated in favour of `org-roam-capture-templates`, which in Org-roam v2 has\na different list structure.  Consult [the manual](doc/orb-manual.org) for more\ndetails**\n\nOrg Roam BibTeX v0.5.2 is the last version of ORB that works with Org-roam v1.\nIt can be found on the branch `orb-v0.5`.\n\nA word of warning 🚧\n---------------\n\n`org-roam-bibtex` is in **Alpha**.\n\nThis means that a lot of things may change in the future (e.g. renaming\nvariables, rewriting functions).  As a result, the package will be unstable for\na while.  This will change when we release v1.0, but for now, you will have to\nbe on the lookout for a few things:\n\n1. If you encounter a problem with the package, start by making sure that you\n   have the latest version. (cf. [Installation](#installation))\n2. If there is a problem with your configuration, most notably variables which\n   do not exist anymore or functions which are not called with the right number\n   of arguments, you will need to check this page to see what has changed.\n3. If neither 1. nor 2. resolved your problem, read the following section on\n   [how to get help](#orb-help-me).\n\n\u003ca name=\"orb-help-me\"\u003e\u003c/a\u003eGetting help\n---------------\n\nPlease read carefully this section before installing Org Roam BibTeX.  We are\nglad to help you in case something does not work as expected.  However, we\nkindly ask you to follow these simple rules when asking for help:\n\n1. Read carefully this README file.\n2. Read it once again, please.  Consult the [extended manual](doc/orb-manual.org)\n3. Check our [community resources](#community) and describe your problem there.\n4. Open an issue on the bug tracker.\n5. Take your time to describe your problem and we'll take ours to help you solve it.\n6. Describe your problem clearly, in a procedural way: \"I run `this command`,\nthen I run `that command`, and finally `this one`.  I expect `this` to happen\nbut instead happens `that`.  Here is my `configuration`.\"\n7. Thank you!\n\nKeep in mind that ORB is under active development and the configuration\nsnippets that you might have found somewhere in the Internet may be outdated\nand be the actual cause your errors.  It is therefore highly recommended to use\nthis README file, [the manual](doc/orb-manual.org) and the Emacs built-in\ndocstrings as primary documentation sources.\n\nInstallation\n---------------\n\n### Hard dependencies\n\nOrg Roam BibTeX depends on [Org Roam](https://github.com/org-roam/org-roam) and\n[BibTeX Completion](https://github.com/tmalsburg/helm-bibtex).  Users cloning\nORB directly from GitHub also need to install the above packages.  When\ninstalling ORB with a package manager (MELPA) or from within a configuration\nframework (Doom, Spacemacs), no additional steps are required.\n\n### Soft dependencies\n\nSome parts of Org Roam BibTeX will not work without: \n\n* [Org Ref](https://github.com/jkitchin/org-ref) — namely when Org-ref v2 or v3\n  citation citation links are used as ROAM_REFS.  Org-roam and ORB now support\n  the built-in Org-cite citation keys (Org mode version 9.5+), so Org-ref is\n  not a strict requirement anymore.\n* [Helm/Ivy-bibtex](https://github.com/tmalsburg/helm-bibtex) — these packages\n  are required by Org-ref and provide native interfaces for Bibtex-completion,\n  although the latter can be installed separately without them.\n* [Citar](https://github.com/bdarcus/citar) — this package provides an extended\n  support for Org-cite citations. You will need to install the companion\n  package [Citar-org-roam](https://github.com/emacs-citar/citar-org-roam), and\n  configure it as described\n  [here](https://github.com/emacs-citar/citar/wiki/Notes-configuration#org-roam-bibtex).\n* [AnyStyle CLI](https://github.com/inukshuk/anystyle-cli) — ORB PDF Scrapper\nrequires this external tool, see [Orb Anystyle](#orb-anystyle) for more\ndetails.\n\n* ORB offers basic completion functions based on Emacs native completion\n  interfaces, but user experience can be enhanced with Helm, Ivy and Hydra\n  packages.\n* Users of Projectile and Persp-mode will be pleased to learn that ORB can\n  automatically switch perspective to the Org Roam project when creating a\n  note.\n\n### With Emacs built-in package manager (`package.el`)\n\nThe package is on [MELPA](https://github.com/melpa/melpa).\n\n1. Install `org-roam-bibtex`:\n\n    a) using `package.el`:\n\n    ```\n    M-x package-install RET org-roam-bibtex RET\n    ```\n\n    b) Alternatively, install it with `M-x package-list-packages`.\n\n2. Load and configure the package in your\n[init-file](https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html):\n\n    a) with `use-package`:\n\n    ``` emacs-lisp\n    (use-package org-roam-bibtex\n      :after org-roam\n      :config\n      (require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links\n    ```\n\n    b) Alternatively, require the package if you don't use `use-package`:\n\n    ``` emacs-lisp\n    (require 'org-ref) ; optional: if using Org-ref v2 or v3 citation links\n    (require 'org-roam-bibtex)\n    ```\n\n### Via cloning\n\nYou can also clone the repository somewhere in your `load-path`.  If you would\nlike to assist with development, this is the way to go.\n\nTo do that:\n\n1. Create a directory where you’d like to clone the repository, e.g. `mkdir\n   ~/projects`.\n\n2. `cd ~/projects`\n\n3. `git clone https://github.com/org-roam/org-roam-bibtex.git`\n\n4. Load and configure the package:\n\n    a) with `use-package`:\n\n    ```emacs-lisp\n    (use-package org-roam-bibtex\n      :after org-roam\n      :load-path \"~/projects/org-roam-bibtex/\" ; Modify with your own path where you cloned the repository\n      :config\n      (require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links\n    ```\n\n    b) Alternatively, if you don't use `use-package`: \n\n    ```emacs-lisp\n    (require 'org-ref) ; optional: if using Org-ref v2 or v3 citation links\n    (add-to-list 'load-path \"~/projects/org-roam-bibtex/\") ; Modify with your own path where you cloned the repository\n    (require 'org-roam-bibtex)\n    ```\n\n### Spacemacs\n\nIf you have a private `org-roam` layer, modify it as follows:\n\n``` emacs-lisp\n(defconst org-roam-packages\n  '(org-roam org-roam-bibtex))\n\n ;; add this after `org-roam/init-org-roam`:\n\n(defun org-roam/init-org-roam-bibtex ()\n  (use-package org-roam-bibtex\n    :after org-roam\n    :config\n    (require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links\n```\n\nIf you don't have a private `org-roam` layer, configure it first, see examples\n[here](https://org-roam.discourse.group/t/orb-helm-bibtex-open-notes-wont-create-new-note/690)\nand\n[here](https://www.reddit.com/r/emacs/comments/f6erh0/total_noob_how_do_i_install_orgroam_in_spacemacs/).\n\nRecent versions of Spacemacs ship with a built-in `org-roam` support, so you\nwon't need a private `org-roam` layer.  You still need a private layer for\n`org-roam-bibtex`.  Consult Spacemacs documentation on how to create one, or\nuse the approach described in the above mentioned resources.\n\n### Doom Emacs\n\n1. Put this in `$DOOMDIR/packages.el`:\n\n``` emacs-lisp\n(package! org-roam-bibtex\n  :recipe (:host github :repo \"org-roam/org-roam-bibtex\"))\n\n;; When using org-roam via the `+roam` flag\n(unpin! org-roam)\n\n;; When using bibtex-completion via the `biblio` module\n(unpin! bibtex-completion helm-bibtex ivy-bibtex)\n```\n\n2. Put this in `$DOOMDIR/config.el`: \n\n``` emacs-lisp\n(use-package! org-roam-bibtex\n  :after org-roam\n  :config\n  (require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links\n```\n\n3. Run `bin/doom sync -u` and restart Emacs.\n\nUsage\n---------------\n\n#### `org-roam-bibtex-mode`\n\nCall interactively `org-roam-bibtex-mode` or arrange your init file to perform\nthis automatically.\n\nYou can now access your bibliographical notes in `org-roam-directory` with\n`helm-bibtex`/`ivy-bibtex` or by opening `org-ref` links.  ORB modifies the\nbehaviour of the above packages to make them use `orb-edit-note` instead of\ntheir default note-management commands.  To get their default behaviour back,\ndisable `org-roam-bibtex-mode`.\n\n#### `orb-note-actions`\n\nType `M-x orb-note-actions` to easily access additional commands useful in\nnote's context.  These commands are run with the note's BibTeX key as an\nargument. The key is taken from the `:ROAM_REFS:` file or heading property.\n\n#### `orb-insert-link`\n\nSelect a bibliography entry and insert a link to a note associated with it.  If\nthe note does not exist yet, create it.  Similar to `org-roam-node-insert`, if a\nregion is selected, it becomes the link description.\n\n#### `org-roam-buffer` sections\n\nThree bibliography related `org-roam-buffer` sections are available.\nThey may be added to the `org-roam-mode-sections` variable.  These\nare:\n\n - `orb-section-reference` displays a formatted reference for the\n   current entry.\n - `orb-section-abstract` displays the abstract (if available) of the\n   current entry.\n - `orb-section-file` displays a link to open the attached file, if\n   such file exists.\n\nConfiguration\n---------------\n\nSee [the Org Roam BibTeX Manual](doc/orb-manual.org) for configuration options and\nadvanced usage.\n\nCommunity\n---------------\nFor help, support, or if you just want to\nhang out with us, you can find us here:\n\n* **IRC**: channel **#org-roam** on [Libera Chat](https://libera.chat/guides/connect)\n* **Slack**: channel **#org-roam-bibtex** on [Org Roam](https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg)\n* **Discourse**: [Org Roam Discourse group](https://org-roam.discourse.group)\n\nChangelog\n---------------\nChangelog is being maintained [here](https://github.com/org-roam/org-roam-bibtex/blob/master/CHANGELOG.md).\n\nLicense\n---------------\nCopyright © 2020-2022 Mykhailo Shevchuk\n\nCopyright © 2020 Leo Vivier\n\nAnd contributros.\n\nDistributed under the GNU General Public License , see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forg-roam%2Forg-roam-bibtex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forg-roam%2Forg-roam-bibtex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forg-roam%2Forg-roam-bibtex/lists"}